qvaluelist.3qt

linux下GUI编程工具qt的在线连接帮助手册

'\" t
.TH QValueList 3qt "11 October 2001" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2001 Trolltech AS.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QValueList \- Value-based template class that provides doubly linked lists
.PP
\fC#include <qvaluelist.h>\fR
.PP
Inherited by QCanvasItemList, QStringList and QValueStack.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "typedef QValueListIterator<T> \fBiterator\fR"
.br
.ti -1c
.BI "typedef QValueListConstIterator<T> \fBconst_iterator\fR"
.br
.ti -1c
.BI "typedef T \fBvalue_type\fR"
.br
.ti -1c
.BI "typedef value_type * \fBpointer\fR"
.br
.ti -1c
.BI "typedef const value_type * \fBconst_pointer\fR"
.br
.ti -1c
.BI "typedef value_type & \fBreference\fR"
.br
.ti -1c
.BI "typedef const value_type & \fBconst_reference\fR"
.br
.ti -1c
.BI "typedef size_t \fBsize_type\fR"
.br
.ti -1c
.BI "\fBQValueList\fR ()"
.br
.ti -1c
.BI "\fBQValueList\fR ( const QValueList<T> & l )"
.br
.ti -1c
.BI "\fBQValueList\fR ( const std::list<T> & l )"
.br
.ti -1c
.BI "\fB~QValueList\fR ()"
.br
.ti -1c
.BI "QValueList<T> & \fBoperator=\fR ( const QValueList<T> & l )"
.br
.ti -1c
.BI "QValueList<T> & \fBoperator=\fR ( const std::list<T> & l )"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const std::list<T> & l ) const"
.br
.ti -1c
.BI "bool \fBoperator==\fR ( const QValueList<T> & l ) const"
.br
.ti -1c
.BI "bool \fBoperator!=\fR ( const QValueList<T> & l ) const"
.br
.ti -1c
.BI "iterator \fBbegin\fR ()"
.br
.ti -1c
.BI "const_iterator \fBbegin\fR () const"
.br
.ti -1c
.BI "iterator \fBend\fR ()"
.br
.ti -1c
.BI "const_iterator \fBend\fR () const"
.br
.ti -1c
.BI "iterator \fBinsert\fR ( iterator it, const T & x )"
.br
.ti -1c
.BI "uint \fBremove\fR ( const T & x )"
.br
.ti -1c
.BI "void \fBclear\fR ()"
.br
.ti -1c
.BI "QValueList<T> & \fBoperator<<\fR ( const T & x )"
.br
.ti -1c
.BI "size_type \fBsize\fR () const"
.br
.ti -1c
.BI "bool \fBempty\fR () const"
.br
.ti -1c
.BI "void \fBpush_front\fR ( const T & x )"
.br
.ti -1c
.BI "void \fBpush_back\fR ( const T & x )"
.br
.ti -1c
.BI "iterator \fBerase\fR ( iterator it )"
.br
.ti -1c
.BI "iterator \fBerase\fR ( iterator first, iterator last )"
.br
.ti -1c
.BI "reference \fBfront\fR ()"
.br
.ti -1c
.BI "const_reference \fBfront\fR () const"
.br
.ti -1c
.BI "reference \fBback\fR ()"
.br
.ti -1c
.BI "const_reference \fBback\fR () const"
.br
.ti -1c
.BI "void \fBpop_front\fR ()"
.br
.ti -1c
.BI "void \fBpop_back\fR ()"
.br
.ti -1c
.BI "void \fBinsert\fR ( iterator pos, size_type n, const T & x )"
.br
.ti -1c
.BI "QValueList<T> \fBoperator+\fR ( const QValueList<T> & l ) const"
.br
.ti -1c
.BI "QValueList<T> & \fBoperator+=\fR ( const QValueList<T> & l )"
.br
.ti -1c
.BI "iterator \fBfromLast\fR ()"
.br
.ti -1c
.BI "const_iterator \fBfromLast\fR () const"
.br
.ti -1c
.BI "bool \fBisEmpty\fR () const"
.br
.ti -1c
.BI "iterator \fBappend\fR ( const T & x )"
.br
.ti -1c
.BI "iterator \fBprepend\fR ( const T & x )"
.br
.ti -1c
.BI "iterator \fBremove\fR ( iterator it )"
.br
.ti -1c
.BI "T & \fBfirst\fR ()"
.br
.ti -1c
.BI "const T & \fBfirst\fR () const"
.br
.ti -1c
.BI "T & \fBlast\fR ()"
.br
.ti -1c
.BI "const T & \fBlast\fR () const"
.br
.ti -1c
.BI "T & \fBoperator[]\fR ( size_type i )"
.br
.ti -1c
.BI "const T & \fBoperator[]\fR ( size_type i ) const"
.br
.ti -1c
.BI "iterator \fBat\fR ( size_type i )"
.br
.ti -1c
.BI "const_iterator \fBat\fR ( size_type i ) const"
.br
.ti -1c
.BI "iterator \fBfind\fR ( const T & x )"
.br
.ti -1c
.BI "const_iterator \fBfind\fR ( const T & x ) const"
.br
.ti -1c
.BI "iterator \fBfind\fR ( iterator it, const T & x )"
.br
.ti -1c
.BI "const_iterator \fBfind\fR ( const_iterator it, const T & x ) const"
.br
.ti -1c
.BI "int \fBfindIndex\fR ( const T & x ) const"
.br
.ti -1c
.BI "size_type \fBcontains\fR ( const T & x ) const"
.br
.ti -1c
.BI "size_type \fBcount\fR () const"
.br
.ti -1c
.BI "QValueList<T> & \fBoperator+=\fR ( const T & x )"
.br
.ti -1c
.BI "typedef QValueListIterator<T> \fBIterator\fR"
.br
.ti -1c
.BI "typedef QValueListConstIterator<T> \fBConstIterator\fR"
.br
.in -1c
.SH RELATED FUNCTION DOCUMENTATION
.in +1c
.ti -1c
.BI "QDataStream & \fBoperator>>\fR ( QDataStream & s, QValueList<T> & l )"
.br
.ti -1c
.BI "QDataStream & \fBoperator<<\fR ( QDataStream & s, const QValueList<T> & l )"
.br
.in -1c
.SH DESCRIPTION
The QValueList class is a value-based template class that provides doubly linked lists.
.PP
QValueList is a Qt implementation of an STL-like list container. It can be used in your application if the standard \fClist\fR is not available. QValueList is part of the Qt Template Library.
.PP
QValueList<T> defines a template instance to create a list of values that all have the class T. Note that QValueList does not store pointers to the members of the list; it holds a copy of every member. This is why these kinds of classes are called "value based"; QPtrList and QDict are "pointer based".
.PP
QValueList contains and manages a collection of objects of type T and provides iterators that allow the contained objects to be addressed. QValueList owns the contained items. For more relaxed ownership semantics, see QPtrCollection and friends which are pointer-based containers.
.PP
Some classes cannot be used within a QValueList, for example, all classes derived from QObject and thus all classes that implement widgets. Only values can be used in a QValueList. To qualify as a value the class must provide:
.TP
A copy constructor
.TP
An assignment operator
.TP
A default constructor, i.e. a constructor that does not take any arguments.
.PP
Note that C++ defaults to field-by-field assignment operators and copy constructors if no explicit version is supplied. In many cases this is sufficient.
.PP
QValueList's function naming is consistent with the other Qt classes (e.g., count(), isEmpty()). QMap also provides extra functions for compatibility with STL algorithms, such as size() and empty(). Programmers already familiar with the STL \fClist\fR can use these functions instead.
.PP
Example:
.PP
.nf
.br
class Employee
.br
{
.br
public:
.br
    Employee(): sn(0) {}
.br
    Employee( const QString& forename, const QString& surname, int salary )
.br
        : fn(forename), sn(surname), sal(salary)
.br
    {}
.br
.br
    QString forename() const { return fn; }
.br
    QString surname() const { return sn; }
.br
    int salary() const { return sal; }
.br
    void setSalary( int salary ) { sal = salary; }
.br
private:
.br
    QString fn;
.br
    QString sn;
.br
    int sal;
.br
};
.br
.br
    typedef QValueList<Employee> EmployeeList;
.br
    EmployeeList list;
.br
.br
    list.append( Employee("John", "Doe", 50000) );
.br
    list.append( Employee("Jane", "Williams", 80000) );
.br
    list.append( Employee("Tom", "Jones", 60000) );
.br
.br
    Employee mary( "Mary", "Hawthorne", 90000 );
.br
    list.append( mary );
.br
    mary.setSalary( 100000 );
.br
.br
    EmployeeList::iterator it;
.br
    for ( it = list.begin(); it != list.end(); ++it )
.br
        cout << (*it).surname().latin1() << ", " <<
.br
                (*it).forename().latin1() << " earns " <<
.br
                (*it).salary() << endl;
.br
.br
    // Output:
.br
    // Doe, John earns 50000
.br
    // Williams, Jane earns 80000
.br
    // Hawthorne, Mary earns 90000
.br
    // Jones, Tom earns 60000
.br
.fi
.PP
Notice that the latest changes to Mary's salary did not affect the value in the list because the list created a copy of Mary's entry.
.PP
There are several ways to find items in the list. The begin() and end() functions return iterators to the beginning and end of the list. The advantage of getting an iterator is that you can move forward or backward from this position by incrementing/decrementing the iterator. The iterator returned by end() points to the item which is one past the last item in the container. The past-the-end iterator is still associated with the list it belongs to, however it is \fInot\fR dereferenceable; operator*() will not return a well-defined value. If the list is empty(), the iterator returned by begin() will equal the iterator returned by end().
.PP
Another way to find an item in the list is by using the qFind() algorithm. For example:
.PP
.nf
.br
    QValueList<int> list;
.br
    ...
.br
    QValueList<int>::iterator it = qFind( list.begin(), list.end(), 3 );
.br
    if ( it != list.end() )
.br
        // it points to the found item
.fi
.PP
It is safe to have multiple iterators on the list at the same time. If some member of the list is removed, only iterators pointing to the removed member become invalid. Inserting into the list does not invalidate any iterator. For convenience, the function last() returns a reference to the last item in the list, and first() returns a reference to the the first item. If the list is empty(), both last() and first() have undefined behavior (your application will crash or do unpredictable things). Use last() and first() with caution, for example:
.PP
.nf
.br
    QValueList<int> list;
.br
    list.append( 1 );
.br
    list.append( 2 );
.br
    list.append( 3 );
.br
    ...
.br
    if ( !list.empty() ) {
.br
        // OK, modify the first item
.br
        int& i = list.first();
.br
        i = 18;
.br
    }
.br
    ...