qtools/qtl.doc

   1 /****************************************************************************
   2 **
   3 **
   4 ** Qt template library classes documentation
   5 **
   6 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
   7 **
   8 ** This file is part of the Qt GUI Toolkit.
   9 **
  10 ** This file may be distributed under the terms of the Q Public License
  11 ** as defined by Trolltech AS of Norway and appearing in the file
  12 ** LICENSE.QPL included in the packaging of this file.
  13 **
  14 ** This file may be distributed and/or modified under the terms of the
  15 ** GNU General Public License version 2 as published by the Free Software
  16 ** Foundation and appearing in the file LICENSE.GPL included in the
  17 ** packaging of this file.
  18 **
  19 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
  20 ** licenses may use this file in accordance with the Qt Commercial License
  21 ** Agreement provided with the Software.
  22 **
  23 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
  24 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  25 **
  26 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
  27 **   information about Qt Commercial License Agreements.
  28 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
  29 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
  30 **
  31 ** Contact info@trolltech.com if any conditions of this licensing are
  32 ** not clear to you.
  33 **
  34 **********************************************************************/
  35
  36 /*!
  37 \page qtl.html
  38
  39 \title Qt Template library
  40
  41 Thq Qt Template Library is a set of templates within Qt dealing with
  42 containers of objects.  It provides a list of objects, a stack of
  43 objects, a map (or dictionary) from one type to another, and
  44 associated iterators and algorithms.
  45
  46 Qt also contains similar classes that deal with pointers to objects;
  47 \l QValueList vs. \l QList, etc.  Compared to the pointer-based
  48 templates, the QTL offers easy copying of the container, real support
  49 for classes that e.g. require constructors, expand to much more object
  50 code, can often be a bit faster, require that the objects stored can
  51 be copied, and finally, have a worse record of compiler problems.
  52
  53 Compared to the STL, the QTL contains only the most important features
  54 of the STL, has more regular function naming, has no platform
  55 differences, is often a little slower and often expands to less object
  56 code.
  57
  58
  59 If you can not make copies of the objects you want to store you are
  60 better off with QCollection and friends. They were designed to handle
  61 exactly that kind of pointer semantics. This applies for example to
  62 all classes derived from \l QObject. A QObject does not have a copy
  63 constructor, so using it as value is impossible. You may choose be
  64 store pointers to QObjects in a QValueList, but using QList directly
  65 seems to be the better choice for this kind of application
  66 domain. QList, like all other QCollection based containers, provides
  67 far more sanity checking than a speed-optimized value
  68 based container.
  69
  70 If you have objects that implement value semantics, use the Qt
  71 template library.  Value semantics require at least
  72 <ul>
  73 <li>a copy constructor,
  74 <li>an assignment operator and
  75 <li> a default constructor, i.e. a constructor that does not take
  76 any arguments.
  77 </ul>
  78 Note that a fast copy constructor is absolutely crucial for a good
  79 overall performance of the container, since many copy operations are
  80 going to happen.
  81
  82 Examples for value based classes are QRect, QPoint, QSize and all
  83 simple C++ types like int, bool or double.
  84
  85 The Qt template library is designed for speed. Especially iterators
  86 are extremely fast. On the drawback side, less error checking is done
  87 than in the QCollection based containers. A template library container
  88 for example does not track associated iterators. This makes certain
  89 validity checks, like on removing items, impossible to perform
  90 automatically.
  91
  92 <h2> Iterators </h2>
  93
  94 The Qt template library deals with value objects, not with pointers.
  95 For that reason, there is no other way of iterating over containers
  96 than using iterators. This is no disadvantage as the size of an
  97 iterator matches the size of a normal pointer - 32 or 64 bits
  98 depending on your CPU architecture.
  99
 100 To iterate over a container, use a loop like this:
 101
 102 \code
 103         typedef QValueList<int> List;
 104         List l;
 105         for( List::Iterator it = l.begin(); it != l.end(); ++it )
 106                 printf("Number is %i\n",*it);
 107 \endcode
 108
 109 begin() returns the iterator pointing at the first element, while
 110 end() returns an iterator that points \e after the last
 111 element. end() marks an invalid position, it can never be
 112 dereferenced. It's the break condition in any iteration, may it be
 113 from begin() or fromLast(). For maximum speed, use increment or
 114 decrement iterators with the prefix operator (++it, --it) instead of the the
 115 postfix one (it++, it--), since the former is slightly faster.
 116
 117 The same concept applies to the other container classes:
 118
 119 \code
 120         typedef QMap<QString,QString> Map;
 121         Map map;
 122         for( Map::Iterator it = map.begin(); it != map.end(); ++it )
 123                 printf("Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() );
 124
 125         typedef QArray<int> Array;
 126         Array array;
 127         for( Array::Iterator it = array.begin(); it != array.end(); ++it )
 128                 printf("Data=%i\n", *it );
 129 \endcode
 130
 131 There are two kind of iterators, the volatile iterator shown in the
 132 examples above and a version that returns a const reference to its
 133 current object, the ConstIterator. Const iterators are required
 134 whenever the container itself is const, such as a member variable
 135 inside a const function. Assigning a ConstIterator to a normal
 136 Iterator is not allowed as it would violate const semantics.
 137
 138 <h2> Algorithms </h2>
 139
 140 The template library defines a number of algorithms that operate on
 141 its containers: qHeapSort(), qBubbleSort(), qSwap() and
 142 qCopy(). These algorithms are implemented as template functions.
 143
 144 qHeapSort() and qBubbleSort() provide the well known sorting
 145 algorithms. You can use them like this:
 146
 147 \code
 148         typedef QValueList<int> List;
 149         List l;
 150         l << 42 << 100 << 1234 << 12 << 8;
 151         qHeapSort( l );
 152
 153         List l2;
 154         l2 << 42 << 100 << 1234 << 12 << 8;
 155         List::Iterator b = l2.find( 100 );
 156         List::Iterator e = l2.find( 8 );
 157         qHeapSort( b, e );
 158
 159         double arr[] = { 3.2, 5.6, 8.9 };
 160         qHeapSort( arr, arr + 3 );
 161 \endcode
 162
 163 The first example sorts the entire list. The second one sorts all
 164 elements enclosed in the two iterators, namely 100, 1234 and 12.  The
 165 third example shows that iterators act like pointers and can be
 166 treated as such.
 167
 168 Naturally, the sorting templates won't work with const iterators.
 169
 170 Another utility is qSwap(). It exchanges the values of two variables:
 171
 172 \code
 173         QString second( "Einstein" );
 174         QString name( "Albert" );
 175         qSwap( second, name );
 176 \endcode
 177
 178 Another template function is qCopy(). It copies a container or a slice
 179 of it to an OutputIterator, in this case a QTextOStreamIterator:
 180
 181 \code
 182         typedef QValueList<int> List;
 183         List l;
 184         l << 100 << 200 << 300;
 185         QTextOStream str( stdout );
 186         qCopy( l, QTextOStreamIterator( str ) );
 187 \endcode
 188
 189 In addition, you can use any Qt template library iterator as the
 190 OutputIterator. Just make sure that the right hand of the iterator has
 191 as many elements present as you want to insert. The following example
 192 illustrates this:
 193
 194 \code
 195         QStringList l1, l2;
 196         l1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
 197         l2 << "Torben" << "Matthias";
 198         qCopy( l2, l1.begin();
 199 \endcode
 200
 201 At the end of this code fragment, the List l1 contains "Torben",
 202 "Matthias", "Arnt" and "Sue", with the prior contents being
 203 overwritten. Another flavor of qCopy() takes three arguments to make
 204 it possible to copy a slice of a container:
 205
 206 \code
 207         typedef QValueList<int> List;
 208         List l;
 209         l << 42 << 100 << 1234 << 12 << 8;
 210         List::Iterator b = l.find( 100 );
 211         List::Iterator e = l.find( 8 );
 212         QTextOStream str( stdout );
 213         qCopy( b, e, QTextOStreamIterator( str ) );
 214 \endcode
 215
 216 If you write new algorithms, consider writing them as template
 217 functions in order to make them usable with as many containers
 218 possible.  In the above example, you could just as easily print out a
 219 standard C++ array with qCopy():
 220
 221 \code
 222         int arr[] = { 100, 200, 300 };
 223         QTextOStream str( stdout );
 224         qCopy( arr, arr + 3, QTextOStreamIterator( str ) );
 225 \endcode
 226
 227
 228 <h2> Streaming </h2>
 229
 230 All mentioned containers can be serialized with the respective
 231 streaming operators. Here is an example.
 232
 233 \code
 234         QDataStream str(...);
 235         QValueList<QRect> l;
 236         // ... fill the list here
 237         str << l;
 238 \endcode
 239
 240 The container can be read in again with:
 241
 242 \code
 243         QValueList<QRect> l;
 244         str >> l;
 245 \endcode
 246
 247 The same applies to QStringList, QValueStack and QMap.
 248
 249 */