| Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | |
The QValueList class is a value-based template class that provides lists. More...
All the functions in this class are reentrant when Qt is built with thread support.
#include <qvaluelist.h>
Inherited by QCanvasItemList, QStringList, and QValueStack.
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 for your target platform(s). 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 items. 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:
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's function naming is consistent with the other Qt classes (e.g. count(), isEmpty()). QValueList also provides extra functions for compatibility with STL algorithms, such as size() and empty(). Programmers already familiar with the STL list may prefer to use the STL-compatible functions.
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.append( Employee("John", "Doe", 50000) );
list.append( Employee("Jane", "Williams", 80000) );
list.append( Employee("Tom", "Jones", 60000) );
Employee mary( "Mary", "Hawthorne", 90000 );
list.append( 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 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 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().
Another way to find an item 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 item
It is safe to have multiple iterators a 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:
QValueList<int> list;
list.append( 1 );
list.append( 2 );
list.append( 3 );
...
if ( !list.empty() ) {
// OK, modify the first item
int& i = list.first();
i = 18;
}
...
QValueList<double> dlist;
double d = dlist.last(); // undefined
Because QValueList is value-based there is no need to be careful about deleting items 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, i.e. O(1). 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 does not affect the other instances; this takes O(n) time. 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 items into the list. The prepend() and append() functions insert items 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 items at specific positions within the list.
Items can also be removed from the list in several ways. There are several variants of the remove() function, which removes a specific item from the list. The remove() function will find and remove items according to a specific item value.
Lists can also be sorted with the sort() function, or can be sorted using the Qt Template Library. For example with qHeapSort():
Example:
QValueList<int> list;
list.append( 5 );
list.append( 8 );
list.append( 3 );
list.append( 4 );
qHeapSort( list );
See also QValueListIterator, Qt Template Library Classes, Implicitly and Explicitly Shared Classes, and Non-GUI Classes.
This iterator is an instantiation of QValueListConstIterator for
the same type as this QValueList. In other words, if you
instantiate QValueList Functionally, this is almost the same as Iterator. The only
difference is you cannot use ConstIterator for non-const
operations, and that the compiler can often generate better code
if you use ConstIterator.
See also QValueListIterator and Iterator.
This iterator is an instantiation of QValueListIterator for the
same type as this QValueList. In other words, if you instantiate
QValueList Functionally, this is almost the same as ConstIterator. The only
difference is that you cannot use ConstIterator for non-const
operations, and that the compiler can often generate better code
if you use ConstIterator.
See also QValueListIterator and ConstIterator.
Constructs an empty list.
Constructs a copy of l.
This operation takes O(1) time because QValueList is implicitly shared.
The first modification to a list will take O(n) time.
Contructs a copy of l.
This constructor is provided for compatibility with STL
containers.
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.
Inserts x at the end of the list.
See also insert() and prepend().
Examples: checklists/checklists.cpp and fonts/simple-qfont-demo/viewer.cpp.
Returns an iterator pointing to the item at position i in the
list, or end() if the index is out of range.
Warning: This function uses a linear search and can be extremely
slow for large lists. QValueList is not optimized for random item
access. If you need random access use a different container, such
as QValueVector.
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.
Returns a reference to the last item. If the list contains no last
item (i.e. empty() returns TRUE), the return value is undefined.
This function is provided for STL compatibility. It is equivalent
to last().
See also front().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator pointing to the first item in the list. This
iterator equals end() if the list is empty.
See also first(), end(), and constBegin().
Examples: canvas/canvas.cpp, chart/canvasview.cpp, chart/element.cpp, checklists/checklists.cpp, sql/overview/insert/main.cpp, table/statistics/statistics.cpp, and themes/themes.cpp.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator pointing to the first item in the list. This
iterator equals end() if the list is empty.
Removes all items from the list.
See also remove().
Returns an iterator pointing to the first item in the list. This
iterator equals constEnd() if the list is empty.
See also begin().
Returns an iterator pointing past the last item in the list.
This iterator equals constBegin() if the list is empty.
See also end().
Returns the number of occurrences of the value x in the list.
Returns the number of items in the list.
See also isEmpty().
Examples: chart/element.cpp and table/statistics/statistics.cpp.
Returns TRUE if the list contains no items; otherwise returns
FALSE.
See also size().
Returns an iterator pointing past the last item in the list.
This iterator equals begin() if the list is empty.
See also last(), begin(), and constEnd().
Examples: canvas/canvas.cpp, chart/canvasview.cpp, chart/element.cpp, checklists/checklists.cpp, sql/overview/insert/main.cpp, table/statistics/statistics.cpp, and themes/themes.cpp.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator pointing past the last item in the list.
This iterator equals begin() if the list is empty.
Removes the item pointed to by it from the list. No iterators
other than it or other iterators pointing at the same item as
it are invalidated. Returns an iterator to the next item after
it, or end() if there is no such item.
This function is provided for STL compatibility. It is equivalent
to remove().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Deletes all items from first to last (not including last). No iterators are invalidated, except those pointing to the
removed items themselves. Returns last.
Returns an iterator pointing to the first occurrence of x in
the list.
Returns end() is no item matched.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator pointing to the first occurrence of x in
the list.
Returns end() if no item matched.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Finds the first occurrence of x in the list starting at the
position given by it.
Returns end() if no item matched.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Finds the first occurrence of x in the list starting at the
position given by it.
Returns end() if no item matched.
Returns the index of the first occurrence of the value x.
Returns -1 if no item matched.
Returns a reference to the first item. If the list contains no
first item (i.e. isEmpty() returns TRUE), the return value is
undefined.
See also last().
Example: network/mail/smtp.cpp.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator to the last item in the list, or end() if
there is no last item.
Use the end() function instead. For example:
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns an iterator to the last item in the list, or end() if
there is no last item.
Use the end() function instead. For example:
Returns a reference to the first item. If the list contains no
first item (i.e. empty() returns TRUE), the return value is
undefined.
This function is provided for STL compatibility. It is equivalent
to first().
See also back().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Inserts the value x in front of the item pointed to by the
iterator, it.
Returns an iterator pointing at the inserted item.
See also append() and prepend().
Example: themes/themes.cpp.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Inserts n copies of x before position pos.
Returns TRUE if the list contains no items; otherwise returns
FALSE.
See also count().
Examples: fonts/simple-qfont-demo/viewer.cpp and network/mail/smtp.cpp.
Returns a reference to the last item. If the list contains no last
item (i.e. empty() returns TRUE), the return value is undefined.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Compares both lists.
Returns TRUE if this list and l are unequal; otherwise returns
FALSE.
Creates a new list and fills it with the items of this list. Then
the items of l are appended. Returns the new list.
Appends the items of l to this list. Returns a reference to
this list.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Appends the value x to the list. Returns a reference to the
list.
Adds the value x to the end of the list.
Returns a reference to the list.
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.
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.
Compares both lists.
Returns TRUE if this list and l are equal; otherwise returns
FALSE.
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.
This operator is provided for compatibility with STL containers.
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.
Warning: This function uses a linear search and can be extremely
slow for large lists. QValueList is not optimized for random item
access. If you need random access use a different container, such
as QValueVector.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns a non-const reference to the item with index i.
Removes the last item. If there is no last item, this operation is
undefined.
This function is provided for STL compatibility.
Removes the first item. If there is no first item, this operation
is undefined.
This function is provided for STL compatibility.
Inserts x at the beginning of the list.
See also insert() and append().
Inserts x at the end of the list.
This function is provided for STL compatibility. It is equivalent
to append().
Inserts x at the beginning of the list.
This function is provided for STL compatibility. It is equivalent
to prepend().
Removes the item pointed to by it from the list. No iterators
other than it or other iterators pointing at the same item as
it are invalidated. Returns an iterator to the next item after
it, or end() if there is no such item.
See also clear().
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Removes all items that have value x and returns the number of
removed items.
Returns the number of items in the list.
This function is provided for STL compatibility. It is equivalent
to count().
See also empty().
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.
Reads a list, l, from the stream s. The type T stored in the
list must implement the streaming operator.
This file is part of the Qt toolkit.
Copyright © 1995-2003
Trolltech. All Rights Reserved.QValueList::Iterator
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 ()
QValueList::QValueList ( const QValueList<T> & l )
QValueList::QValueList ( const std::list<T> & l )
QValueList::~QValueList ()
iterator QValueList::append ( const T & x )
const_iterator QValueList::at ( size_type i ) const
iterator QValueList::at ( size_type i )
reference QValueList::back ()
const_reference QValueList::back () const
const_iterator QValueList::begin () const
iterator QValueList::begin ()
void QValueList::clear ()
const_iterator QValueList::constBegin () const
const_iterator QValueList::constEnd () const
size_type QValueList::contains ( const T & x ) const
size_type QValueList::count () const
bool QValueList::empty () const
iterator QValueList::end ()
const_iterator QValueList::end () const
iterator QValueList::erase ( iterator it )
iterator QValueList::erase ( iterator first, iterator last )
iterator QValueList::find ( const T & x )
const_iterator QValueList::find ( const T & x ) const
iterator QValueList::find ( iterator it, const T & x )
const_iterator QValueList::find ( const_iterator it, const T & x ) const
int QValueList::findIndex ( const T & x ) const
T & QValueList::first ()
const T & QValueList::first () const
const_iterator QValueList::fromLast () const
QValueList<int> l;
...
QValueList<int>::iterator it = l.end();
--it;
if ( it != end() )
// ...
iterator QValueList::fromLast ()
QValueList<int> l;
...
QValueList<int>::iterator it = l.end();
--it;
if ( it != end() )
// ...
reference QValueList::front ()
const_reference QValueList::front () const
iterator QValueList::insert ( iterator it, const T & x )
void QValueList::insert ( iterator pos, size_type n, const T & x )
bool QValueList::isEmpty () const
T & QValueList::last ()
const T & QValueList::last () const
bool QValueList::operator!= ( const QValueList<T> & l ) const
QValueList<T> QValueList::operator+ ( const QValueList<T> & l ) const
QValueList<T> & QValueList::operator+= ( const QValueList<T> & l )
QValueList<T> & QValueList::operator+= ( const T & x )
QValueList<T> & QValueList::operator<< ( const T & x )
QValueList<T> & QValueList::operator= ( const QValueList<T> & l )
QValueList<T> & QValueList::operator= ( const std::list<T> & l )
bool QValueList::operator== ( const QValueList<T> & l ) const
bool QValueList::operator== ( const std::list<T> & l ) const
const T & QValueList::operator[] ( size_type i ) const
T & QValueList::operator[] ( size_type i )
void QValueList::pop_back ()
void QValueList::pop_front ()
iterator QValueList::prepend ( const T & x )
void QValueList::push_back ( const T & x )
void QValueList::push_front ( const T & x )
iterator QValueList::remove ( iterator it )
uint QValueList::remove ( const T & x )
size_type QValueList::size () const
Related Functions
QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )
QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )
Copyright © 2003
Trolltech Trademarks
Qt version 3.2.0b2