Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions | ![]() |
The QValueList class is a value-based template class that provides doubly linked lists. More...
#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. QValueList is part of the Qt Template Library.
QValueList 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:
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:
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:
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:
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:
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 often can 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 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.
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.
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.
The push_back() function should be used instead. For example:
Examples: checklists/checklists.cpp and fonts/simple-qfont-demo/viewer.cpp.
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.
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 element. If the list contains no
last element (i.e. empty() returns TRUE), the return value is
undefined.
Returns a reference to the last element. If the list contains no
last element (i.e. empty() returns TRUE), the return value is
undefined.
Returns an iterator pointing to the first element in the list. This
iterator equals end() if the list is empty.
Examples: checklists/checklists.cpp, dirview/dirview.cpp, fonts/simple-qfont-demo/viewer.cpp, network/ftpclient/ftpmainwindow.cpp, network/ftpclient/ftpview.cpp and sql/overview/insert/main.cpp.
Returns an iterator pointing to the first element in the list. This
iterator equals end() if the list is empty.
Removes all items from the list.
See also remove().
Use the std::count() or qCount() algorithms instead.
Use the size() function instead.
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.
Returns TRUE if the list's size is zero; otherwise returns FALSE.
Returns an iterator pointing behind the last element in the list. This
iterator equals begin() if the list is empty.
Examples: checklists/checklists.cpp, dirview/dirview.cpp, fonts/simple-qfont-demo/viewer.cpp, network/ftpclient/ftpmainwindow.cpp, network/ftpclient/ftpview.cpp and sql/overview/insert/main.cpp.
Returns an iterator pointing behind the last element in the list. This
iterator equals begin() if the list is empty.
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.
Deletes all elements from first to last (not including last). No iterators are invalidated, except those pointing to the
removed elements themselves. Returns last.
Use the std::find() or qFind() algorithms instead.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use the std::find() or qFind() algorithms instead.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use the std::find() or qFind() algorithms instead.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use the std::find() or qFind() algorithms instead.
Use the std::find() or qFind() algorithms instead.
Use the front() function instead.
Example: network/mail/smtp.cpp.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use the front() function instead.
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:
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:
Returns a reference to the first element. If the list contains no
first element (i.e. empty() returns TRUE), the return value is
undefined.
Returns a reference to the first element. If the list contains no
first element (i.e. empty() returns TRUE), the return value is
undefined.
Inserts the value x in front of the iterator it.
Returns an iterator pointing at the inserted item.
See also append() and prepend().
Inserts n copies of x before position pos.
Use the empty() function instead.
See also size().
Examples: fonts/simple-qfont-demo/viewer.cpp, network/ftpclient/ftpmainwindow.cpp and network/mail/smtp.cpp.
Use the back() function instead.
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Use the back() function instead.
Compares both lists.
Returns TRUE if this list and l are unequal; otherwise returns FALSE.
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.
The std::copy() or qCopy algorithms should be used instead. For
example:
Adds 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.
The push_back() function should be used instead. For example:
Adds the value x to the end of 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.
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.
Returns TRUE if this list and l are equal; otherwise returns FALSE.
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.
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.
Removes the last element. If there is no last element, this
operation is undefined.
Removes the first element. If there is no first element, this
operation is undefined.
The push_front() function should be used instead. For example:
Inserts x at the end of the list.
Inserts x at the beginning of the list.
Removes all items that have value x and returns the number of removed
items.
See also clear().
Use the erase() function instead.
See also clear().
Returns the number of elements in the list.
Example: network/ftpclient/ftpview.cpp.
Writes a list, l, to the stream s. The type T stored in the
list must implement the streaming operator, too.
Reads a list, l, from the stream s. The type T stored in the
list must implement the streaming operator, too.
This file is part of the Qt toolkit,
copyright © 1995-2001
Trolltech, all rights reserved.
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
QValueList<int> list;
...
QValueList<int>::iterator it = qFind( list.begin(), list.end(), 3 );
if ( it != list.end() )
// it points to the found element
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)
QValueList<int> l;
l.push_back( 5 );
l.push_back( 8 );
l.push_back( 3 );
l.push_back( 4 );
qHeapSort( l );
Member Type Documentation
QValueList::ConstIterator
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 ()
Constructs an empty list.
QValueList::QValueList ( const QValueList<T> & l )
QValueList::QValueList ( const std::list<T> & l )
Contructs a copy of l.
QValueList::~QValueList ()
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.
QValueList<int> list;
list.push_back( 1 );
const_iterator QValueList::at ( size_type i ) const
iterator QValueList::at ( size_type i )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
reference QValueList::back ()
const_reference QValueList::back () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
const_iterator QValueList::begin () const
iterator QValueList::begin ()
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
void QValueList::clear ()
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.
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.
void QValueList::detach () [protected]
bool QValueList::empty () const
iterator QValueList::end ()
const_iterator QValueList::end () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
iterator QValueList::erase ( iterator pos )
iterator QValueList::erase ( iterator first, iterator last )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
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.
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.
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.
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.
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.
T & QValueList::first ()
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
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.
const_iterator QValueList::fromLast () const
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.
QValueList<int> l;
...
QValueList<int>::iterator it = l.end();
--it;
if ( it != end() )
// ...
reference QValueList::front ()
const_reference QValueList::front () const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
iterator QValueList::insert ( iterator it, const T & x )
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.
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.
T & QValueList::last ()
This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.
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.
bool QValueList::operator!= ( const QValueList<T> & l ) const
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.
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.
QValueList<int> l1;
QValueList<int> l2;
...
std::copy( l2.begin(), l2.end(), std::back_inserter( l1 ) );
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.
QValueList<int> list;
list.push_back( 1 );
QValueList<T> & QValueList::operator<< ( const T & x )
QValueList<T> & QValueList::operator= ( const QValueList<T> & l )
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.
bool QValueList::operator== ( const QValueList<T> & l ) const
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.
const T & QValueList::operator[] ( size_type i ) const
T & QValueList::operator[] ( size_type i )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
void QValueList::pop_back ()
void QValueList::pop_front ()
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.
QValueList<int> list;
list.push_front( 2 );
list.push_front( 1 );
void QValueList::push_back ( const T & x )
void QValueList::push_front ( const T & x )
uint QValueList::remove ( const T & x )
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.
size_type QValueList::size () const
Related Functions
QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )
Copyright © 2001
Trolltech Trademarks