1 /****************************************************************************
4 ** Qt template library classes documentation
6 ** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
8 ** This file is part of the Qt GUI Toolkit.
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.
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.
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.
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.
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.
31 ** Contact info@trolltech.com if any conditions of this licensing are
34 **********************************************************************/
39 \title Qt Template library
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.
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.
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
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
70 If you have objects that implement value semantics, use the Qt
71 template library. Value semantics require at least
73 <li>a copy constructor,
74 <li>an assignment operator and
75 <li> a default constructor, i.e. a constructor that does not take
78 Note that a fast copy constructor is absolutely crucial for a good
79 overall performance of the container, since many copy operations are
82 Examples for value based classes are QRect, QPoint, QSize and all
83 simple C++ types like int, bool or double.
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
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.
100 To iterate over a container, use a loop like this:
103 typedef QValueList<int> List;
105 for( List::Iterator it = l.begin(); it != l.end(); ++it )
106 printf("Number is %i\n",*it);
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.
117 The same concept applies to the other container classes:
120 typedef QMap<QString,QString> 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() );
125 typedef QArray<int> Array;
127 for( Array::Iterator it = array.begin(); it != array.end(); ++it )
128 printf("Data=%i\n", *it );
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.
138 <h2> Algorithms </h2>
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.
144 qHeapSort() and qBubbleSort() provide the well known sorting
145 algorithms. You can use them like this:
148 typedef QValueList<int> List;
150 l << 42 << 100 << 1234 << 12 << 8;
154 l2 << 42 << 100 << 1234 << 12 << 8;
155 List::Iterator b = l2.find( 100 );
156 List::Iterator e = l2.find( 8 );
159 double arr[] = { 3.2, 5.6, 8.9 };
160 qHeapSort( arr, arr + 3 );
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
168 Naturally, the sorting templates won't work with const iterators.
170 Another utility is qSwap(). It exchanges the values of two variables:
173 QString second( "Einstein" );
174 QString name( "Albert" );
175 qSwap( second, name );
178 Another template function is qCopy(). It copies a container or a slice
179 of it to an OutputIterator, in this case a QTextOStreamIterator:
182 typedef QValueList<int> List;
184 l << 100 << 200 << 300;
185 QTextOStream str( stdout );
186 qCopy( l, QTextOStreamIterator( str ) );
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
196 l1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
197 l2 << "Torben" << "Matthias";
198 qCopy( l2, l1.begin();
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:
207 typedef QValueList<int> List;
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 ) );
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():
222 int arr[] = { 100, 200, 300 };
223 QTextOStream str( stdout );
224 qCopy( arr, arr + 3, QTextOStreamIterator( str ) );
230 All mentioned containers can be serialized with the respective
231 streaming operators. Here is an example.
234 QDataStream str(...);
236 // ... fill the list here
240 The container can be read in again with:
247 The same applies to QStringList, QValueStack and QMap.