/**************************************************************************** ** ** TQt Template Library classes documentation ** ** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. ** ** This file is part of the TQt GUI Toolkit. ** ** This file may be used under the terms of the GNU General ** Public License versions 2.0 or 3.0 as published by the Free ** Software Foundation and appearing in the files LICENSE.GPL2 ** and LICENSE.GPL3 included in the packaging of this file. ** Alternatively you may (at your option) use any later version ** of the GNU General Public License if such license has been ** publicly approved by Trolltech ASA (or its successors, if any) ** and the KDE Free TQt Foundation. ** ** Please review the following information to ensure GNU General ** Public Licensing requirements will be met: ** http://trolltech.com/products/qt/licenses/licensing/opensource/. ** If you are unsure which license is appropriate for your use, please ** review the following information: ** http://trolltech.com/products/qt/licenses/licensing/licensingoverview ** or contact the sales department at sales@trolltech.com. ** ** This file may be used under the terms of the Q Public License as ** defined by Trolltech ASA and appearing in the file LICENSE.QPL ** included in the packaging of this file. Licensees holding valid Qt ** Commercial licenses may use this file in accordance with the Qt ** Commercial License Agreement provided with the Software. ** ** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, ** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR ** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted ** herein. ** **********************************************************************/ /*! \page qt-template-lib.html \title TQt Template Library The TQt Template Library (TQTL) is a set of templates that provide object containers. If a suitable STL implementation is not available on all your target platforms, the TQTL can be used instead. It provides a list of objects, a vector (dynamic array) of objects, a map relating one type to another (also called a dictionary or associative array), and associated \link #Iterators iterators\endlink and \link #Algorithms algorithms\endlink. A container is an object which contains and manages other objects and provides iterators that allow the contained objects to be accessed. The TQTL classes' naming conventions are consistent with the other Qt classes (e.g., count(), isEmpty()). They also provide extra functions for compatibility with STL algorithms, such as size() and empty(). Programmers already familiar with the STL \c map can use the STL-compatible functions if preferred. Compared to the STL, the TQTL only contains the most important features of the STL container API. Compared with the STL, TQTL has no platform differences, but is often a little slower and often expands to less object code. If you cannot make copies of the objects you want to store you should use TQPtrCollection and friends, all of which operate on pointers rather than values. This applies, for example, to all classes derived from \l TQObject. A TQObject does not have a copy constructor, so using it as value is impossible. You may choose to store pointers to TQObjects in a TQValueList, but using TQPtrList directly seems to be the better choice for this kind of application domain. TQPtrList, like all other TQPtrCollection based containers, provides far more sanity checking than a speed-optimized value based container. If you have objects that implement value semantics, and the STL is not available on your target platform, the TQt Template Library can be used instead. Value semantics require at least: \list \i a copy constructor; \i an assignment operator; \i a defaultconstructor, i.e. a constructor that does not take any arguments. \endlist Note that a fast copy constructor is absolutely crucial to achieve good overall performance of the container, since many copy operations will occur. If you intend sorting your data you must implement \c{operator<()} for your data's class. Good candidates for value based classes are TQRect, TQPoint, TQSize, TQString and all simple C++ types, such as int, bool or double. The TQt Template Library is designed for speed. Iterators are extremely fast. To achieve this performance, less error checking is done than in the TQPtrCollection based containers. A TQTL container, for example, does not track any associated iterators. This makes certain validity checks, for example when removing items, impossible to perform automatically, but does lead to extremely good performance. \target Iterators \section1 Iterators The TQt Template Library deals with value objects, not with pointers. For that reason, there is no other way of iterating over containers other than with iterators. This is no disadvantage as the size of an iterator matches the size of a normal pointer. To iterate over a container, use a loop like this: \code typedef TQValueList List; List list; for( List::Iterator it = list.begin(); it != list.end(); ++it ) printf( "Number is %i\n", *it ); \endcode begin() returns the iterator pointing at the first element, while end() returns an iterator that points \e after the last element. end() marks an invalid position, so it can never be dereferenced. It's the break condition in any iteration, whether the start point is from begin() or fromLast(). For maximum speed, use increment or decrement iterators with the prefix operator (++it, --it) instead of the postfix operator (it++, it--), since the former is slightly faster. The same concept applies to the other container classes: \code typedef TQMap Map; Map map; for( Map::iterator it = map.begin(); it != map.end(); ++it ) printf( "Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() ); typedef TQValueVector Vector; Vector vec; for( Vector::iterator it = vec.begin(); it != vec.end(); ++it ) printf( "Data=%d\n", *it ); \endcode There are two kind of iterators, the volatile iterator shown in the examples above and a version that returns a const reference to its current object, the ConstIterator. Const iterators are required whenever the container itself is const, such as a member variable inside a const function. Assigning a ConstIterator to a normal Iterator is not allowed as it would violate const semantics. \target Algorithms \section1 Algorithms The TQt Template Library defines a number of algorithms that operate on its containers. These algorithms are implemented as template functions and provide useful generic code which can be applied to any container that provides iterators (including your own containers). \section2 qHeapSort() qHeapSort() provides a well known sorting algorithm. You can use it like this: \code typedef TQValueList List; List list; list << 42 << 100 << 1234 << 12 << 8; qHeapSort( list ); List list2; list2 << 42 << 100 << 1234 << 12 << 8; List::Iterator b = list2.find( 100 ); List::Iterator e = list2.find( 8 ); qHeapSort( b, e ); double arr[] = { 3.2, 5.6, 8.9 }; qHeapSort( arr, arr + 3 ); \endcode The first example sorts the entire list. The second example sorts only those elements that fall between the two iterators, i.e. 100, 1234 and 12. The third example shows that iterators act like pointers and can be treated as such. If using your own data types you must implement \c{operator<()} for your data's class. Naturally, the sorting templates won't work with const iterators. \target tqSwap \section2 tqSwap() tqSwap() exchanges the values of two variables: \code TQString second( "Einstein" ); TQString name( "Albert" ); tqSwap( second, name ); \endcode \target tqCount \section2 tqCount() The tqCount() template function counts the number of occurrences of a value within a container. For example: \code TQValueList list; list.push_back( 1 ); list.push_back( 1 ); list.push_back( 1 ); list.push_back( 2 ); int c = 0; tqCount( list.begin(), list.end(), 1, c ); // c == 3 \endcode \target tqFind \section2 tqFind() The tqFind() template function finds the first occurrence of a value within a container. For example: \code TQValueList list; list.push_back( 1 ); list.push_back( 1 ); list.push_back( 1 ); list.push_back( 2 ); TQValueListIterator it = tqFind( list.begin(), list.end(), 2 ); \endcode \target tqFill \section2 tqFill() The tqFill() template function fills a range with copies of a value. For example: \code TQValueVector vec(3); tqFill( vec.begin(), vec.end(), 99 ); // vec contains 99, 99, 99 \endcode \target tqEqual \section2 tqEqual() The tqEqual() template function compares two ranges for equality of their elements. Note that the number of elements in each range is not considered, only if the elements in the first range are equal to the corresponding elements in the second range (consequently, both ranges must be valid). For example: \code TQValueVector v1(3); v1[0] = 1; v1[2] = 2; v1[3] = 3; TQValueVector v2(5); v2[0] = 1; v2[2] = 2; v2[3] = 3; v2[4] = 4; v2[5] = 5; bool b = tqEqual( v1.begin(), v2.end(), v2.begin() ); // b == TRUE \endcode \target tqCopy \section2 tqCopy() The tqCopy() template function copies a range of elements to an OutputIterator, in this case a TQTextOStreamIterator: \code TQValueList list; list.push_back( 100 ); list.push_back( 200 ); list.push_back( 300 ); TQTextOStream str( stdout ); tqCopy( list.begin(), list.end(), TQTextOStreamIterator(str) ); \endcode \omit Here is another example which copies a range of elements from one container into another. It uses the qBackInserter() template function which creates a QBackInsertIterator<> whose job is to insert elements into the end of a container. For example: \code TQValueList l; l.push_back( 100 ); l.push_back( 200 ); l.push_back( 300 ); TQValueVector v; tqCopy( l.begin(), l.end(), qBackInserter(v) ); \endcode \endomit \target tqCopyBackward \section2 tqCopyBackward() The tqCopyBackward() template function copies a container or a slice of a container to an OutputIterator, but in reverse order, for example: \code TQValueVector vec(3); vec.push_back( 100 ); vec.push_back( 200 ); vec.push_back( 300 ); TQValueVector another; tqCopyBackward( vec.begin(), vec.end(), another.begin() ); // 'another' now contains 100, 200, 300 // however the elements are copied one at a time // in reverse order (300, 200, then 100) \endcode \section2 TQTL Iterators You can use any TQt Template Library iterator as the OutputIterator. Just make sure that the right hand of the iterator has as many elements present as you want to insert. The following example illustrates this: \code TQStringList list1, list2; list1 << "Weis" << "Ettrich" << "Arnt" << "Sue"; list2 << "Torben" << "Matthias"; tqCopy( list2.begin(), list2.end(), list1.begin() ); TQValueVector vec( list1.size(), "Dave" ); tqCopy( list2.begin(), list2.end(), vec.begin() ); \endcode At the end of this code fragment, the list list1 contains "Torben", "Matthias", "Arnt" and "Sue", with the prior contents being overwritten. The vector vec contains "Torben", "Matthias", "Dave" and "Dave", also with the prior contents being overwritten. If you write new algorithms, consider writing them as template functions in order to make them usable with as many containers as possible. In the above example, you could just as easily print out a standard C++ array with tqCopy(): \code int arr[] = { 100, 200, 300 }; TQTextOStream str( stdout ); tqCopy( arr, arr + 3, TQTextOStreamIterator( str ) ); \endcode \section1 Streaming All the containers we've mentioned can be serialized with the appropriate streaming operators. Here is an example. \code TQDataStream str(...); TQValueList list; // ... fill the list here str << list; \endcode The container can be read in again with: \code TQValueList list; str >> list; \endcode The same applies to TQStringList, TQValueStack and TQMap. */ /*! \fn TQPair qMakePair(T1 t1, T2 t2) \relates TQPair This is a template convenience function. It is used to create a TQPair\<\> object that contains \a t1 and \a t2. */