From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qt-template-lib.html | 320 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 doc/html/qt-template-lib.html (limited to 'doc/html/qt-template-lib.html') diff --git a/doc/html/qt-template-lib.html b/doc/html/qt-template-lib.html new file mode 100644 index 000000000..e4f75444f --- /dev/null +++ b/doc/html/qt-template-lib.html @@ -0,0 +1,320 @@ + + + + + +TQt Template Library + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

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 iterators and algorithms. 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 TQt +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 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 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 retquire at least: +

+

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 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. +

+

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: +

+    typedef TQValueList<int> List;
+    List list;
+    for( List::Iterator it = list.begin(); it != list.end(); ++it )
+        printf( "Number is %i\n", *it );
+
+ +

begin() returns the iterator pointing at the first element, while +end() returns an iterator that points 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: +

+    typedef TQMap<TQString,TQString> 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<int> Vector;
+    Vector vec;
+    for( Vector::iterator it = vec.begin(); it != vec.end(); ++it )
+        printf( "Data=%d\n", *it );
+
+ +

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 retquired +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. +

+

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). +

qHeapSort() +

+

qHeapSort() provides a well known sorting algorithm. You can use it +like this: +

+    typedef TQValueList<int> 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 );
+
+ +

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 operator<() for +your data's class. +

Naturally, the sorting templates won't work with const iterators. +

+

qSwap() +

+

qSwap() exchanges the values of two variables: +

+    TQString second( "Einstein" );
+    TQString name( "Albert" );
+    qSwap( second, name );
+
+ +

+

qCount() +

+

The qCount() template function counts the number of occurrences of a +value within a container. For example: +

+    TQValueList<int> list;
+    list.push_back( 1 );               
+    list.push_back( 1 );               
+    list.push_back( 1 );               
+    list.push_back( 2 );               
+    int c = 0;
+    qCount( list.begin(), list.end(), 1, c ); // c == 3
+
+ +

+

qFind() +

+

The qFind() template function finds the first occurrence of a value +within a container. For example: +

+    TQValueList<int> list;
+    list.push_back( 1 );               
+    list.push_back( 1 );               
+    list.push_back( 1 );               
+    list.push_back( 2 );               
+    TQValueListIterator<int> it = qFind( list.begin(), list.end(), 2 );
+
+ +

+

qFill() +

+

The qFill() template function fills a range with copies of a value. +For example: +

+    TQValueVector<int> vec(3);
+    qFill( vec.begin(), vec.end(), 99 ); // vec contains 99, 99, 99
+
+ +

+

qEqual() +

+

The qEqual() 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: +

+    TQValueVector<int> v1(3);
+    v1[0] = 1;
+    v1[2] = 2;
+    v1[3] = 3;
+
+    TQValueVector<int> v2(5);
+    v2[0] = 1;
+    v2[2] = 2;
+    v2[3] = 3;
+    v2[4] = 4;
+    v2[5] = 5;
+
+    bool b = qEqual( v1.begin(), v2.end(), v2.begin() );
+    // b == TRUE
+
+ +

+

qCopy() +

+

The qCopy() template function copies a range of elements to an +OutputIterator, in this case a TQTextOStreamIterator: +

+    TQValueList<int> list;
+    list.push_back( 100 );
+    list.push_back( 200 );
+    list.push_back( 300 );
+    TQTextOStream str( stdout );
+    qCopy( list.begin(), list.end(), TQTextOStreamIterator(str) );
+
+ +

+

+

qCopyBackward() +

+

The qCopyBackward() template function copies a container or a slice of +a container to an OutputIterator, but in reverse order, for example: +

+    TQValueVector<int> vec(3);
+    vec.push_back( 100 );
+    vec.push_back( 200 );
+    vec.push_back( 300 );
+    TQValueVector<int> another;
+    qCopyBackward( 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)
+
+ +

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: +

+    TQStringList list1, list2;
+    list1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
+    list2 << "Torben" << "Matthias";
+    qCopy( list2.begin(), list2.end(), list1.begin() );
+
+    TQValueVector<TQString> vec( list1.size(), "Dave" );
+    qCopy( list2.begin(), list2.end(), vec.begin() );
+
+ +

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 qCopy(): +

+    int arr[] = { 100, 200, 300 };
+    TQTextOStream str( stdout );
+    qCopy( arr, arr + 3, TQTextOStreamIterator( str ) ); 
+
+ +

Streaming +

+

All the containers we've mentioned can be serialized with the +appropriate streaming operators. Here is an example. +

+    TQDataStream str(...);
+    TQValueList<TQRect> list;
+    // ... fill the list here
+    str << list;
+
+ +

The container can be read in again with: +

+    TQValueList<TQRect> list;
+    str >> list;
+
+ +

The same applies to TQStringList, TQValueStack and TQMap. + + +


+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1