QValueList(3qt)

NAME
QValueList - Value-based template class that provides doubly linked lists

#include <qvaluelist.h>

Inherited by QCanvasItemList, QStringList and QValueStack.

  Public Members
typedef QValueListIterator<T> iterator
typedef QValueListConstIterator<T> const_iterator
typedef T value_type
typedef value_type * pointer
typedef const value_type * const_pointer
typedef value_type & reference
typedef const value_type & const_reference
typedef size_t size_type
QValueList ()
QValueList ( const QValueList<T> & l )
QValueList ( const std::list<T> & l )
~QValueList ()
QValueList<T> & operator= ( const QValueList<T> & l )
QValueList<T> & operator= ( const std::list<T> & l )
bool operator== ( const std::list<T> & l ) const
bool operator== ( const QValueList<T> & l ) const
bool operator!= ( const QValueList<T> & l ) const
iterator begin ()
const_iterator begin () const
iterator end ()
const_iterator end () const
iterator insert ( iterator it, const T & x )
uint remove ( const T & x )
void clear ()
QValueList<T> & operator<< ( const T & x )
size_type size () const
bool empty () const
void push_front ( const T & x )
void push_back ( const T & x )
iterator erase ( iterator pos )
iterator erase ( iterator first, iterator last )
reference front ()
const_reference front () const
reference back ()
const_reference back () const
void pop_front ()
void pop_back ()
void insert ( iterator pos, size_type n, const T & x )
QValueList<T> operator+ ( const QValueList<T> & l ) const (obsolete)
QValueList<T> & operator+= ( const QValueList<T> & l ) (obsolete)
iterator fromLast ()
const_iterator fromLast () const
bool isEmpty () const (obsolete)
iterator append ( const T & x ) (obsolete)
iterator prepend ( const T & x ) (obsolete)
iterator remove ( iterator it ) (obsolete)
T & first () (obsolete)
const T & first () const (obsolete)
T & last () (obsolete)
const T & last () const (obsolete)
T & operator[] ( size_type i )
const T & operator[] ( size_type i ) const
iterator at ( size_type i )
const_iterator at ( size_type i ) const
iterator find ( const T & x ) (obsolete)
const_iterator find ( const T & x ) const (obsolete)
iterator find ( iterator it, const T & x ) (obsolete)
const_iterator find ( const_iterator it, const T & x ) const (obsolete)
int findIndex ( const T & x ) const (obsolete)
size_type contains ( const T & x ) const (obsolete)
size_type count () const (obsolete)
QValueList<T> & operator+= ( const T & x ) (obsolete)
typedef QValueListIterator<T> Iterator
typedef QValueListConstIterator<T> ConstIterator

  Protected Members
void detach ()

RELATED FUNCTION DOCUMENTATION
QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )
QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )

DESCRIPTION
The QValueList class is a value-based template class that provides doubly linked lists.

QValueList is a Qt implementation of an STL-like list container. It can be used in your application if the standard list<> is not available. QValueList is part of the Qt Template Library.

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".

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 elements. For more relaxed ownership semantics, see QPtrCollection and friends which are pointer-based containers.

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:

A copy constructor

An assignment operator

A default constructor, i.e. a constructor that does not take any arguments.

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.

QValueList uses an STL-like syntax to manipulate and address the objects it contains. For historical reasons, QValueList contains additional functions which essentially perform the same task. It is recommended that the STL-like functions be used in application code. See this document for more information.

Example:

class Employee
{
public:
    Employee(): sn(0) {}
    Employee( const QString& forename, const QString& surname, int salary )
        : fn(forename), sn(surname), sal(salary)
    {}
    QString forename() const { return fn; }
    QString surname() const { return sn; }
    int salary() const { return sal; }
    void setSalary( int salary ) { sal = salary; }
private:
    QString fn;
    QString sn;
    int sal;
};
    typedef QValueList<Employee> EmployeeList;
    EmployeeList list;
    list.push_back( Employee("John", "Doe", 50000) );
    list.push_back( Employee("Jane", "Williams", 80000) );
    list.push_back( Employee("Tom", "Jones", 60000) );
    Employee mary( "Mary", "Hawthorne", 90000 );
    list.push_back( mary );
    mary.setSalary( 100000 );
    EmployeeList::iterator it;
    for ( it = list.begin(); it != list.end(); ++it )
        cout << (*it).surname().latin1() << ", " <<
                (*it).forename().latin1() << " earns " <<
                (*it).salary() << endl;
    // Output:
    // Doe, John earns 50000
    // Williams, Jane earns 80000
    // Hawthorne, Mary earns 90000
    // Jones, Tom earns 60000

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.

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 element which is one past the last element in the container. The past-the-end iterator is still associated with the list it belongs to, however it is not 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(). Since end() returns a past-the-end iterator, the size() of the list is equal to end() - begin().

Another way to find an element in the list is by using the qFind() algorithm. For example:

    QValueList<int> list;
    ...
    QValueList<int>::iterator it = qFind( list.begin(), list.end(), 3 );
    if ( it != list.end() )
        // it points to the found element

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 back() returns a reference to the last element in the list, and front() returns a reference to the the first element. If the list is empty(), both back() and front() have undefined behavior (your application will crash or do unpredictable things). Use back() and front() with caution, for example:

    QValueList<int> list;
    list.push_back( 1 );
    list.push_back( 2 );
    list.push_back( 3 );
    ...
    if ( !list.empty() ) {
        // OK, modify the first element
        int& i = list.front();
        i = 18;
    }
    ...
    QValueList<double> dlist;
    double d = dlist.back(); // undefined (probably a crash)

Because QValueList is value-based there is no need to be careful about deleting elements in the list. The list holds its own copies and will free them if the corresponding member or the list itself is deleted. You can force the list to free all of its items with clear().

QValueList is shared implicitly, which means it can be copied in constant time. If multiple QValueList instances share the same data and one needs to modify its contents, this modifying instance makes a copy and modifies its private copy; therefore it not affect the other instances. This is often called "copy on write". If a QValueList is being used in a multi-threaded program, you must protect all access to the list. See QMutex.

There are several ways to insert elements into the list. The push_front() and push_back() functions insert elements at the beginning and the end of the list respectively. The insert() function comes in several flavors and can be used to add one or more elements at specific positions within the list.

Items can be also be removed from the list in several ways. There are several variants of the erase() function which removes a specific element from the list. The remove() function will find and remove elements according to a specific element value.

Lists can be also sorted with the sort() function, or can be sorted using the Qt Template Library. For example with qHeapSort():

Example:

    QValueList<int> l;
    l.push_back( 5 );
    l.push_back( 8 );
    l.push_back( 3 );
    l.push_back( 4 );
    qHeapSort( l );

See also QValueListIterator, Qt Template Library Classes, Implicitly and Explicitly Shared Classes and Non-GUI Classes.

  Member Type Documentation

QValueList::ConstIterator
This iterator is an instantiation of QValueListConstIterator for the same type as this QValueList. In other words, if you instantiate QValueList<int>, ConstIterator is a QValueListConstIterator<int>. Several member function use it, such as QValueList::begin(), which returns an iterator pointing to the first item in the list.

Functionally, this is almost the same as Iterator. The only difference is you cannot use ConstIterator for non-const operations, and that the compiler often can generate better code if you use ConstIterator.

See also QValueListIterator and Iterator.

QValueList::Iterator
This iterator is an instantiation of QValueListIterator for the same type as this QValueList. In other words, if you instantiate QValueList<int>, Iterator is a QValueListIterator<int>. Several member function use it, such as QValueList::begin(), which returns an iterator pointing to the first item in the list.

Functionally, this is almost the same as ConstIterator. The only difference is you cannot use ConstIterator for non-const operations, and that the compiler often can generate better code if you use ConstIterator.

See also QValueListIterator and ConstIterator.

QValueList::const_iterator
The list's const iterator type, QValueListConstIterator.

QValueList::const_pointer
The const pointer to T type.

QValueList::const_reference
The const reference to T type.

QValueList::iterator
The list's iterator type, QValueListIterator.

QValueList::pointer
The pointer to T type.

QValueList::reference
The reference to T type.

QValueList::size_type
An unsigned integral type, used to represent various sizes.

QValueList::value_type
The type of the object stored in the list, T.

MEMBER FUNCTION DOCUMENTATION

QValueList::QValueList ()
Constructs an empty list.

QValueList::QValueList ( const QValueList<T> & l )
Constructs a copy of l.

This operation takes O(1) time because QValueList is shared implicitly.

The first modification to a list will take O(n) time.

QValueList::QValueList ( const std::list<T> & l )
Contructs a copy of l.

QValueList::~QValueList ()
Destroys the list. References to the values in the list and all iterators of this list become invalidated. Note that it is impossible for an iterator to check whether or not it is valid - QValueList is highly tuned for performance, not for error checking.

iterator QValueList::append ( const T & x )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

The push_back() function should be used instead. For example:

    QValueList<int> list;
    list.push_back( 1 );

Examples:

const_iterator QValueList::at ( size_type i ) const
Warning: This function uses a linear search and can be extremely slow for large lists. QValueList is not optimized for random element access. If you need random access use a different container, such as QValueVector.

Returns an iterator pointing to the item at position i in the list, or end() if the index is out of range.

iterator QValueList::at ( size_type i )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns an iterator pointing to the item at position i in the list, or end() if the index is out of range.

reference QValueList::back ()
Returns a reference to the last element. If the list contains no last element (i.e. empty() returns TRUE), the return value is undefined.

const_reference QValueList::back () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a reference to the last element. If the list contains no last element (i.e. empty() returns TRUE), the return value is undefined.

const_iterator QValueList::begin () const
Returns an iterator pointing to the first element in the list. This iterator equals end() if the list is empty.

See also first() and end().

Examples:

iterator QValueList::begin ()
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns an iterator pointing to the first element in the list. This iterator equals end() if the list is empty.

See also first() and end().

void QValueList::clear ()
Removes all items from the list.

See also remove().

size_type QValueList::contains ( const T & x ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the std::count() or qCount() algorithms instead.

size_type QValueList::count () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the size() function instead.

void QValueList::detach () [protected]
If the list does not share its data with another QValueList instance, nothing happens. Otherwise the function creates a new copy of this data and detaches from the shared one. This function is called whenever the list is modified. The implicit sharing mechanism is implemented this way.

bool QValueList::empty () const
Returns TRUE if the list's size is zero; otherwise returns FALSE.

iterator QValueList::end ()
Returns an iterator pointing behind the last element in the list. This iterator equals begin() if the list is empty.

See also last() and begin().

Examples:

const_iterator QValueList::end () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns an iterator pointing behind the last element in the list. This iterator equals begin() if the list is empty.

See also last() and begin().

iterator QValueList::erase ( iterator pos )
Deletes the element pointed to by pos from the list. No iterators other than pos or other iterators pointing at the same element as pos are invalidated. Returns an iterator to the next element after pos, or end() if there is no such element.

iterator QValueList::erase ( iterator first, iterator last )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Deletes all elements from first to last (not including last). No iterators are invalidated, except those pointing to the removed elements themselves. Returns last.

iterator QValueList::find ( const T & x )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the std::find() or qFind() algorithms instead.

const_iterator QValueList::find ( const T & x ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Use the std::find() or qFind() algorithms instead.

iterator QValueList::find ( iterator it, const T & x )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Use the std::find() or qFind() algorithms instead.

const_iterator QValueList::find ( const_iterator it, const T & x ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Use the std::find() or qFind() algorithms instead.

int QValueList::findIndex ( const T & x ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the std::find() or qFind() algorithms instead.

T & QValueList::first ()
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the front() function instead.

Example: network/mail/smtp.cpp.

const T & QValueList::first () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Use the front() function instead.

const_iterator QValueList::fromLast () const
Returns an iterator to the last element in the list, or end() if there is no last element.

Use the end() function instead. For example:

    QValueList<int> l;
    ...
    QValueList<int>::iterator it = l.end();
    --it;
    if ( it != end() )
        // ...

iterator QValueList::fromLast ()
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns an iterator to the last element in the list, or end() if there is no last element.

Use the end() function instead. For example:

    QValueList<int> l;
    ...
    QValueList<int>::iterator it = l.end();
    --it;
    if ( it != end() )
        // ...

reference QValueList::front ()
Returns a reference to the first element. If the list contains no first element (i.e. empty() returns TRUE), the return value is undefined.

const_reference QValueList::front () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a reference to the first element. If the list contains no first element (i.e. empty() returns TRUE), the return value is undefined.

iterator QValueList::insert ( iterator it, const T & x )
Inserts the value x in front of the iterator it.

Returns an iterator pointing at the inserted item.

See also append() and prepend().

void QValueList::insert ( iterator pos, size_type n, const T & x )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Inserts n copies of x before position pos.

bool QValueList::isEmpty () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the empty() function instead.

See also size().

Examples:

T & QValueList::last ()
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the back() function instead.

const T & QValueList::last () const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Use the back() function instead.

bool QValueList::operator!= ( const QValueList<T> & l ) const
Compares both lists.

Returns TRUE if this list and l are unequal; otherwise returns FALSE.

QValueList<T> QValueList::operator+ ( const QValueList<T> & l ) const
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

The std::copy() or qCopy() algorithms should be used instead.

Creates a new list and fills it with the elements of this list. Then the elements of l are appended.

Returns the new list.

QValueList<T> & QValueList::operator+= ( const QValueList<T> & l )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

The std::copy() or qCopy algorithms should be used instead. For example:

    QValueList<int> l1;
    QValueList<int> l2;
    ...
    std::copy( l2.begin(), l2.end(), std::back_inserter( l1 ) );

Adds l to this list.

Returns a reference to this list.

QValueList<T> & QValueList::operator+= ( const T & x )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

The push_back() function should be used instead. For example:

    QValueList<int> list;
    list.push_back( 1 );

Adds the value x to the end of the list.

Returns a reference to the list.

QValueList<T> & QValueList::operator<< ( const T & x )
Adds the value x to the end of the list.

Returns a reference to the list.

QValueList<T> & QValueList::operator= ( const QValueList<T> & l )
Assigns l to this list and returns a reference to this list.

All iterators of the current list become invalidated by this operation. The cost of such an assignment is O(1) since QValueList is implicitly shared.

QValueList<T> & QValueList::operator= ( const std::list<T> & l )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Assigns the contents of l to the list.

All iterators of the current list become invalidated by this operation.

bool QValueList::operator== ( const QValueList<T> & l ) const
Compares both lists.

Returns TRUE if this list and l are equal; otherwise returns FALSE.

bool QValueList::operator== ( const std::list<T> & l ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns TRUE if this list and l are equal; otherwise returns FALSE.

const T & QValueList::operator[] ( size_type i ) const
Warning: This function uses a linear search and can be extremely slow for large lists. QValueList is not optimized for random element access. If you need random access use a different container, such as QValueVector.

Returns a const reference to the item with index i in the list. It is up to you to check whether this item really exists. You can do that easily with the count() function. However this operator does not check whether i is in range and will deliver undefined results if it does not exist.

T & QValueList::operator[] ( size_type i )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Warning: This function uses a linear search and can be extremely slow for large lists. QValueList is not optimized for random element access. If you need random access use a different container, such as QValueVector.

Returns a reference to the item with index i in the list. It is up to you to check whether this item really exists. You can do that easily with the count() function. However this operator does not check whether i is in range and will deliver undefined results if it does not exist. In contrast to the const operator[], you may manipulate the value returned by this operator.

void QValueList::pop_back ()
Removes the last element. If there is no last element, this operation is undefined.

void QValueList::pop_front ()
Removes the first element. If there is no first element, this operation is undefined.

iterator QValueList::prepend ( const T & x )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

The push_front() function should be used instead. For example:

    QValueList<int> list;
    list.push_front( 2 );
    list.push_front( 1 );

void QValueList::push_back ( const T & x )
Inserts x at the end of the list.

void QValueList::push_front ( const T & x )
Inserts x at the beginning of the list.

uint QValueList::remove ( const T & x )
Removes all items that have value x and returns the number of removed items.

See also clear().

iterator QValueList::remove ( iterator it )
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Use the erase() function instead.

See also clear().

size_type QValueList::size () const
Returns the number of elements in the list.

Example: network/ftpclient/ftpview.cpp.

RELATED FUNCTION DOCUMENTATION

QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Writes a list, l, to the stream s. The type T stored in the list must implement the streaming operator, too.

QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )
Reads a list, l, from the stream s. The type T stored in the list must implement the streaming operator, too.

SEE ALSO
http://doc.trolltech.com/qvaluelist.html http://www.trolltech.com/faq/tech.html

COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

AUTHOR
Generated automatically from the source code.

BUGS
If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you.

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qvaluelist.3qt) and the Qt version (3.0.0-beta6).