Detailed Description
The Q3ValueList class is a value-based template class that provides lists.
Q3ValueList 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 platforms.
Q3ValueList<T> defines a template instance to create a list of values that all have the class T. Note that Q3ValueList 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"; Q3PtrList and Q3Dict are "pointer based".
Q3ValueList contains and manages a collection of objects of type T and provides iterators that allow the contained objects to be addressed. Q3ValueList owns the contained items. For more relaxed ownership semantics, see Q3PtrCollection and friends which are pointer-based containers.
Some classes cannot be used within a Q3ValueList, for example, all classes derived from QObject and thus all classes that implement widgets. Only values can be used in a Q3ValueList. 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.
In addition, some compilers (e.g. Sun CC) might require that the class provides an equality operator (operator==()).
Q3ValueList's function naming is consistent with the other Qt classes (e.g. count(), isEmpty()). Q3ValueList 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 Q3ValueList<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().
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:
Q3ValueList<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;
}
...
Q3ValueList<double> dlist;
double d = dlist.last(); // undefined
Because Q3ValueList 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().
Q3ValueList is shared implicitly, which means it can be copied in constant time, i.e. O(1). If multiple Q3ValueList 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 Q3ValueList 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.
See also Q3ValueListIterator.
Member Type Documentation
typedef Q3ValueList::ConstIterator
This iterator is an instantiation of Q3ValueListConstIterator for the same type as this Q3ValueList. In other words, if you instantiate Q3ValueList<int>, ConstIterator is a Q3ValueListConstIterator<int>. Several member function use it, such as Q3ValueList::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 can often generate better code if you use ConstIterator.
See also Q3ValueListIterator and Iterator.
typedef Q3ValueList::Iterator
This iterator is an instantiation of Q3ValueListIterator for the same type as this Q3ValueList. In other words, if you instantiate Q3ValueList<int>, Iterator is a Q3ValueListIterator<int>. Several member function use it, such as Q3ValueList::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 that you cannot use ConstIterator for non-const operations, and that the compiler can often generate better code if you use ConstIterator.
See also Q3ValueListIterator and ConstIterator.
typedef Q3ValueList::const_iterator
The list's const iterator type, Q3ValueListConstIterator.
typedef Q3ValueList::const_pointer
The const pointer to T type.
typedef Q3ValueList::const_reference
The const reference to T type.
typedef Q3ValueList::iterator
The list's iterator type, Q3ValueListIterator.
typedef Q3ValueList::pointer
The pointer to T type.
typedef Q3ValueList::reference
The reference to T type.
typedef Q3ValueList::size_type
An unsigned integral type, used to represent various sizes.
typedef Q3ValueList::value_type
The type of the object stored in the list, T.
Member Function Documentation
Q3ValueList::Q3ValueList ()
Constructs an empty list.
Q3ValueList::Q3ValueList ( const Q3ValueList<T> & l )
Constructs a copy of l.
Q3ValueList::Q3ValueList ( const QLinkedList<T> & l )
Constructs a copy of l.
Q3ValueList::Q3ValueList ( const QList<T> & l )
Constructs a copy of l.
Q3ValueList::Q3ValueList ( const std::list<T> & l )
Contructs a copy of l.
This constructor is provided for compatibility with STL containers.
Q3ValueList::~Q3ValueList ()
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: Q3ValueList is highly tuned for performance, not for error checking.
Q3ValueList<T>::Iterator Q3ValueList::append ( const T & x )
Inserts x at the end of the list.
See also insert() and prepend().
Q3ValueList<T>::ConstIterator Q3ValueList::at ( Q3ValueList<T>::size_type i ) const
Returns an iterator pointing to the item at position i in the list, or an undefined value if the index is out of range.
Warning: This function uses a linear search and can be extremely slow for large lists. Q3ValueList is not optimized for random item access. If you need random access use a different container, such as Q3ValueVector.
Q3ValueList<T>::Iterator Q3ValueList::at ( Q3ValueList<T>::size_type i )
This is an overloaded member function, provided for convenience.
Returns an iterator pointing to the item at position i in the list, or an undefined value if the index is out of range.
Q3ValueList<T>::size_type Q3ValueList::contains ( const T & x ) const
Returns the number of occurrences of the value x in the list.
Q3ValueList<T>::ConstIterator Q3ValueList::fromLast () const
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:
Q3ValueList<int> l;
...
Q3ValueList<int>::iterator it = l.end();
--it;
if ( it != end() )
// ...
Q3ValueList<T>::Iterator Q3ValueList::fromLast ()
This is an overloaded member function, provided for convenience.
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:
Q3ValueList<int> l;
...
Q3ValueList<int>::iterator it = l.end();
--it;
if ( it != end() )
// ...
Q3ValueList<T>::Iterator Q3ValueList::insert ( Q3ValueList<T>::Iterator it, const T & x )
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().
void Q3ValueList::insert ( Q3ValueList<T>::Iterator pos, Q3ValueList<T>::size_type n, const T & x )
This is an overloaded member function, provided for convenience.
Inserts n copies of x before position pos.
Q3ValueList<T>::Iterator Q3ValueList::prepend ( const T & x )
Inserts x at the beginning of the list.
See also insert() and append().
Q3ValueList<T>::Iterator Q3ValueList::remove ( Q3ValueList<T>::Iterator it )
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().
int Q3ValueList::remove ( const T & x )
This is an overloaded member function, provided for convenience.
Removes all items that have value x and returns the number of removed items.
Q3ValueList::operator QList<T> () const
Automatically converts a Q3ValueList<T> into a QList<T>.
bool Q3ValueList::operator!= ( const Q3ValueList<T> & l ) const
Compares both lists.
Returns TRUE if this list and l are unequal; otherwise returns FALSE.
Q3ValueList<T> Q3ValueList::operator+ ( const Q3ValueList<T> & l ) const
Creates a new list and fills it with the items of this list. Then the items of l are appended. Returns the new list.
Q3ValueList<T> & Q3ValueList::operator+= ( const Q3ValueList<T> & l )
Appends the items of l to this list. Returns a reference to this list.
Q3ValueList<T> & Q3ValueList::operator+= ( const T & x )
This is an overloaded member function, provided for convenience.
Appends the value x to the list. Returns a reference to the list.
Q3ValueList<T> & Q3ValueList::operator<< ( const T & x )
Adds the value x to the end of the list.
Returns a reference to the list.
Q3ValueList<T> & Q3ValueList::operator= ( const Q3ValueList<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 Q3ValueList is implicitly shared.
Q3ValueList<T> & Q3ValueList::operator= ( const QList<T> & l )
This is an overloaded member function, provided for convenience.
Assigns l to this list and returns a reference to this list.
All iterators of the current list become invalidated by this operation.
Q3ValueList<T> & Q3ValueList::operator= ( const std::list<T> & l )
This is an overloaded member function, provided for convenience.
Assigns the contents of l to the list.
All iterators of the current list become invalidated by this operation.
bool Q3ValueList::operator== ( const Q3ValueList<T> & l ) const
Compares both lists.
Returns TRUE if this list and l are equal; otherwise returns FALSE.
bool Q3ValueList::operator== ( const std::list<T> & l ) const
This is an overloaded member function, provided for convenience.
Returns TRUE if this list and l are equal; otherwise returns FALSE.
This operator is provided for compatibility with STL containers.
const T & Q3ValueList::operator[] ( Q3ValueList<T>::size_type i ) const
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. Q3ValueList is not optimized for random item access. If you need random access use a different container, such as Q3ValueVector.
T & Q3ValueList::operator[] ( Q3ValueList<T>::size_type i )
This is an overloaded member function, provided for convenience.
Returns a non-const reference to the item with index i.
Related Non-Members
QDataStream & operator<< ( QDataStream & s, const Q3ValueList<T> & l )
This is an overloaded member function, provided for convenience.
Writes a list, l, to the stream s. The type T stored in the list must implement the streaming operator.
This is an overloaded member function, provided for convenience.
Reads a list, l, from the stream s. The type T stored in the list must implement the streaming operator.
