TQValueList is a TQt implementation of an STL-like list container. It can be used in your application if the standard \fClist\fR is not available for your target platform(s). TQValueList is part of the TQt Template Library.
TQValueList<T> defines a template instance to create a list of values that all have the class T. Note that TQValueList 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"; TQPtrList and QDict are "pointer based".
TQValueList contains and manages a collection of objects of type T and provides iterators that allow the contained objects to be addressed. TQValueList owns the contained items. For more relaxed ownership semantics, see TQPtrCollection and friends which are pointer-based containers.
Some classes cannot be used within a TQValueList, for example, all classes derived from TQObject and thus all classes that implement widgets. Only values can be used in a TQValueList. To qualify as a value the class must provide:
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.
TQValueList's function naming is consistent with the other TQt classes (e.g. count(), isEmpty()). TQValueList also provides extra functions for compatibility with STL algorithms, such as size() and empty(). Programmers already familiar with the STL \fClist\fR may prefer to use the STL-compatible functions.
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 \fIpast\fR 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().
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:
Because TQValueList 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().
TQValueList is shared implicitly, which means it can be copied in constant time, i.e. O(1). If multiple TQValueList 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 TQValueList is being used in a multi-threaded program, you must protect all access to the list. See TQMutex.
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.
.PP
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.
This iterator is an instantiation of TQValueListConstIterator for the same type as this TQValueList. In other words, if you instantiate TQValueList<int>, ConstIterator is a TQValueListConstIterator<int>. Several member function use it, such as TQValueList::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.
This iterator is an instantiation of TQValueListIterator for the same type as this TQValueList. In other words, if you instantiate TQValueList<int>, Iterator is a TQValueListIterator<int>. Several member function use it, such as TQValueList::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.
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: TQValueList is highly tuned for performance, not for error checking.
.SH "iterator TQValueList::append ( const T & x )"
\fBWarning:\fR This function uses a linear search and can be extremely slow for large lists. TQValueList is not optimized for random item access. If you need random access use a different container, such as TQValueVector.
Removes the item pointed to by \fIit\fR from the list. No iterators other than \fIit\fR or other iterators pointing at the same item as \fIit\fR are invalidated. Returns an iterator to the next item after \fIit\fR, or end() if there is no such item.
.PP
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.
.PP
Deletes all items from \fIfirst\fR to \fIlast\fR (not including \fIlast\fR). No iterators are invalidated, except those pointing to the removed items themselves. Returns \fIlast\fR.
Returns a const reference to the item with index \fIi\fR 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 \fIi\fR is in range and will deliver undefined results if it does not exist.
\fBWarning:\fR This function uses a linear search and can be extremely slow for large lists. TQValueList is not optimized for random item access. If you need random access use a different container, such as TQValueVector.
Removes the item pointed to by \fIit\fR from the list. No iterators other than \fIit\fR or other iterators pointing at the same item as \fIit\fR are invalidated. Returns an iterator to the next item after \fIit\fR, or end() if there is no such item.
