source: trunk/doc/html/qt-template-lib.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 14.5 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qtl.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Qt Template Library</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Qt Template Library</h1>
33
34
35<p>
36<p> The Qt Template Library (QTL) is a set of templates that provide
37object containers. If a suitable STL implementation is not available
38on all your target platforms, the QTL can be used instead. It provides
39a list of objects, a vector (dynamic array) of objects, a map relating
40one type to another (also called a dictionary or associative array),
41and associated <a href="#Iterators">iterators</a> and <a href="#Algorithms">algorithms</a>. A container is an object which
42contains and manages other objects and provides iterators that allow
43the contained objects to be accessed.
44<p> The QTL classes' naming conventions are consistent with the other Qt
45classes (e.g., count(), isEmpty()). They also provide extra functions
46for compatibility with STL algorithms, such as size() and empty().
47Programmers already familiar with the STL <tt>map</tt> can use the
48STL-compatible functions if preferred.
49<p> Compared to the STL, the QTL only contains the most important features
50of the STL container API. Compared with the STL, QTL has no platform
51differences, but is often a little slower and often expands to less
52object code.
53<p> If you cannot make copies of the objects you want to store you should
54use <a href="qptrcollection.html">QPtrCollection</a> and friends, all of which operate on pointers
55rather than values. This applies, for example, to all classes derived
56from <a href="qobject.html">QObject</a>. A <a href="qobject.html">QObject</a> does not have a copy constructor, so using
57it as value is impossible. You may choose to store pointers to
58QObjects in a <a href="qvaluelist.html">QValueList</a>, but using <a href="qptrlist.html">QPtrList</a> directly seems to be the
59better choice for this kind of application domain. QPtrList, like all
60other QPtrCollection based containers, provides far more sanity
61checking than a speed-optimized value based container.
62<p> If you have objects that implement value semantics, and the STL is not
63available on your target platform, the Qt Template Library can be used
64instead. Value semantics require at least:
65<ul>
66<li> a copy constructor;
67<li> an assignment operator;
68<li> a defaultconstructor, i.e. a constructor that does not take any arguments.
69</ul>
70<p> Note that a fast copy constructor is absolutely crucial to achieve
71good overall performance of the container, since many copy operations
72will occur.
73<p> If you intend sorting your data you must implement <a href="qcstring.html#operator-lt-2">operator&lt;</a>() for
74your data's class.
75<p> Good candidates for value based classes are <a href="qrect.html">QRect</a>, <a href="qpoint.html">QPoint</a>, <a href="qsize.html">QSize</a>,
76<a href="qstring.html">QString</a> and all simple C++ types, such as int, bool or double.
77<p> The Qt Template Library is designed for speed. Iterators are extremely
78fast. To achieve this performance, less error checking is done than in
79the <a href="qptrcollection.html">QPtrCollection</a> based containers. A QTL container, for example,
80does not track any associated iterators. This makes certain validity
81checks, for example when removing items, impossible to perform
82automatically, but does lead to extremely good performance.
83<p> <a name="Iterators"></a>
84<h2> Iterators
85</h2>
86<a name="1"></a><p> The Qt Template Library deals with value objects, not with pointers.
87For that reason, there is no other way of iterating over containers
88other than with iterators. This is no disadvantage as the size of an
89iterator matches the size of a normal pointer.
90<p> To iterate over a container, use a loop like this:
91<pre>
92 typedef QValueList&lt;int&gt; List;
93 List list;
94 for( List::Iterator it = list.begin(); it != list.end(); ++it )
95 printf( "Number is %i\n", *it );
96</pre>
97
98<p> begin() returns the iterator pointing at the first element, while
99end() returns an iterator that points <em>after</em> the last element. end()
100marks an invalid position, so it can never be dereferenced. It's the
101break condition in any iteration, whether the start point is from
102begin() or fromLast(). For maximum speed, use increment or decrement
103iterators with the prefix operator (++it, --it) instead of the postfix
104operator (it++, it--), since the former is slightly faster.
105<p> The same concept applies to the other container classes:
106<pre>
107 typedef QMap&lt;QString,QString&gt; Map;
108 Map map;
109 for( Map::iterator it = map.begin(); it != map.end(); ++it )
110 printf( "Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() );
111
112 typedef QValueVector&lt;int&gt; Vector;
113 Vector vec;
114 for( Vector::iterator it = vec.begin(); it != vec.end(); ++it )
115 printf( "Data=%d\n", *it );
116</pre>
117
118<p> There are two kind of iterators, the volatile iterator shown in the
119examples above and a version that returns a const reference to its
120current object, the ConstIterator. Const iterators are required
121whenever the container itself is const, such as a member variable
122inside a const function. Assigning a ConstIterator to a normal
123Iterator is not allowed as it would violate const semantics.
124<p> <a name="Algorithms"></a>
125<h2> Algorithms
126</h2>
127<a name="2"></a><p> The Qt Template Library defines a number of algorithms that operate on
128its containers. These algorithms are implemented as template functions
129and provide useful generic code which can be applied to any container
130that provides iterators (including your own containers).
131<p> <h3> qHeapSort()
132</h3>
133<a name="2-1"></a><p> qHeapSort() provides a well known sorting algorithm. You can use it
134like this:
135<pre>
136 typedef QValueList&lt;int&gt; List;
137 List list;
138 list &lt;&lt; 42 &lt;&lt; 100 &lt;&lt; 1234 &lt;&lt; 12 &lt;&lt; 8;
139 qHeapSort( list );
140
141 List list2;
142 list2 &lt;&lt; 42 &lt;&lt; 100 &lt;&lt; 1234 &lt;&lt; 12 &lt;&lt; 8;
143 List::Iterator b = list2.find( 100 );
144 List::Iterator e = list2.find( 8 );
145 qHeapSort( b, e );
146
147 double arr[] = { 3.2, 5.6, 8.9 };
148 qHeapSort( arr, arr + 3 );
149</pre>
150
151<p> The first example sorts the entire list. The second example sorts only
152those elements that fall between the two iterators, i.e. 100, 1234 and
15312. The third example shows that iterators act like pointers and can
154be treated as such.
155<p> If using your own data types you must implement <a href="qcstring.html#operator-lt-2">operator&lt;</a>() for
156your data's class.
157<p> Naturally, the sorting templates won't work with const iterators.
158<p> <a name="qSwap"></a>
159<h3> qSwap()
160</h3>
161<a name="2-2"></a><p> qSwap() exchanges the values of two variables:
162<pre>
163 <a href="qstring.html">QString</a> second( "Einstein" );
164 <a href="qstring.html">QString</a> name( "Albert" );
165 qSwap( second, name );
166</pre>
167
168<p> <a name="qCount"></a>
169<h3> qCount()
170</h3>
171<a name="2-3"></a><p> The qCount() template function counts the number of occurrences of a
172value within a container. For example:
173<pre>
174 <a href="qvaluelist.html">QValueList</a>&lt;int&gt; list;
175 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
176 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
177 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
178 list.<a href="qvaluelist.html#push_back">push_back</a>( 2 );
179 int c = 0;
180 qCount( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), 1, c ); // c == 3
181</pre>
182
183<p> <a name="qFind"></a>
184<h3> qFind()
185</h3>
186<a name="2-4"></a><p> The qFind() template function finds the first occurrence of a value
187within a container. For example:
188<pre>
189 <a href="qvaluelist.html">QValueList</a>&lt;int&gt; list;
190 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
191 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
192 list.<a href="qvaluelist.html#push_back">push_back</a>( 1 );
193 list.<a href="qvaluelist.html#push_back">push_back</a>( 2 );
194 <a href="qvaluelistiterator.html">QValueListIterator</a>&lt;int&gt; it = qFind( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), 2 );
195</pre>
196
197<p> <a name="qFill"></a>
198<h3> qFill()
199</h3>
200<a name="2-5"></a><p> The qFill() template function fills a range with copies of a value.
201For example:
202<pre>
203 <a href="qvaluevector.html">QValueVector</a>&lt;int&gt; vec(3);
204 qFill( vec.<a href="qvaluevector.html#begin">begin</a>(), vec.<a href="qvaluevector.html#end">end</a>(), 99 ); // vec contains 99, 99, 99
205</pre>
206
207<p> <a name="qEqual"></a>
208<h3> qEqual()
209</h3>
210<a name="2-6"></a><p> The qEqual() template function compares two ranges for equality of
211their elements. Note that the number of elements in each range is not
212considered, only if the elements in the first range are equal to the
213corresponding elements in the second range (consequently, both ranges
214must be valid). For example:
215<pre>
216 <a href="qvaluevector.html">QValueVector</a>&lt;int&gt; v1(3);
217 v1[0] = 1;
218 v1[2] = 2;
219 v1[3] = 3;
220
221 <a href="qvaluevector.html">QValueVector</a>&lt;int&gt; v2(5);
222 v2[0] = 1;
223 v2[2] = 2;
224 v2[3] = 3;
225 v2[4] = 4;
226 v2[5] = 5;
227
228 bool b = qEqual( v1.<a href="qvaluevector.html#begin">begin</a>(), v2.<a href="qvaluevector.html#end">end</a>(), v2.<a href="qvaluevector.html#begin">begin</a>() );
229 // b == TRUE
230</pre>
231
232<p> <a name="qCopy"></a>
233<h3> qCopy()
234</h3>
235<a name="2-7"></a><p> The qCopy() template function copies a range of elements to an
236OutputIterator, in this case a QTextOStreamIterator:
237<pre>
238 <a href="qvaluelist.html">QValueList</a>&lt;int&gt; list;
239 list.<a href="qvaluelist.html#push_back">push_back</a>( 100 );
240 list.<a href="qvaluelist.html#push_back">push_back</a>( 200 );
241 list.<a href="qvaluelist.html#push_back">push_back</a>( 300 );
242 <a href="qtextostream.html">QTextOStream</a> str( stdout );
243 qCopy( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), QTextOStreamIterator(str) );
244</pre>
245
246<p>
247<p> <a name="qCopyBackward"></a>
248<h3> qCopyBackward()
249</h3>
250<a name="2-8"></a><p> The qCopyBackward() template function copies a container or a slice of
251a container to an OutputIterator, but in reverse order, for example:
252<pre>
253 <a href="qvaluevector.html">QValueVector</a>&lt;int&gt; vec(3);
254 vec.<a href="qvaluevector.html#push_back">push_back</a>( 100 );
255 vec.<a href="qvaluevector.html#push_back">push_back</a>( 200 );
256 vec.<a href="qvaluevector.html#push_back">push_back</a>( 300 );
257 <a href="qvaluevector.html">QValueVector</a>&lt;int&gt; another;
258 qCopyBackward( vec.<a href="qvaluevector.html#begin">begin</a>(), vec.<a href="qvaluevector.html#end">end</a>(), another.<a href="qvaluevector.html#begin">begin</a>() );
259 // 'another' now contains 100, 200, 300
260 // however the elements are copied one at a time
261 // in reverse order (300, 200, then 100)
262</pre>
263
264<p> <h3> QTL Iterators
265</h3>
266<a name="2-9"></a><p> You can use any Qt Template Library iterator as the OutputIterator.
267Just make sure that the right hand of the iterator has as many
268elements present as you want to insert. The following example
269illustrates this:
270<p> <pre>
271 <a href="qstringlist.html">QStringList</a> list1, list2;
272 list1 &lt;&lt; "Weis" &lt;&lt; "Ettrich" &lt;&lt; "Arnt" &lt;&lt; "Sue";
273 list2 &lt;&lt; "Torben" &lt;&lt; "Matthias";
274 qCopy( list2.begin(), list2.end(), list1.<a href="qvaluelist.html#begin">begin</a>() );
275
276 <a href="qvaluevector.html">QValueVector</a>&lt;QString&gt; vec( list1.<a href="qvaluelist.html#size">size</a>(), "Dave" );
277 qCopy( list2.begin(), list2.end(), vec.<a href="qvaluevector.html#begin">begin</a>() );
278</pre>
279
280<p> At the end of this code fragment, the list list1 contains "Torben",
281"Matthias", "Arnt" and "Sue", with the prior contents being
282overwritten. The vector vec contains "Torben", "Matthias", "Dave" and
283"Dave", also with the prior contents being overwritten.
284<p> If you write new algorithms, consider writing them as template
285functions in order to make them usable with as many containers
286as possible. In the above example, you could just as easily print out
287a standard C++ array with qCopy():
288<p> <pre>
289 int arr[] = { 100, 200, 300 };
290 <a href="qtextostream.html">QTextOStream</a> str( stdout );
291 qCopy( arr, arr + 3, QTextOStreamIterator( str ) );
292</pre>
293
294<p> <h2> Streaming
295</h2>
296<a name="3"></a><p> All the containers we've mentioned can be serialized with the
297appropriate streaming operators. Here is an example.
298<p> <pre>
299 <a href="qdatastream.html">QDataStream</a> str(...);
300 <a href="qvaluelist.html">QValueList</a>&lt;QRect&gt; list;
301 // ... fill the list here
302 str &lt;&lt; list;
303</pre>
304
305<p> The container can be read in again with:
306<p> <pre>
307 <a href="qvaluelist.html">QValueList</a>&lt;QRect&gt; list;
308 str &gt;&gt; list;
309</pre>
310
311<p> The same applies to <a href="qstringlist.html">QStringList</a>, <a href="qvaluestack.html">QValueStack</a> and <a href="qmap.html">QMap</a>.
312
313<!-- eof -->
314<p><address><hr><div align=center>
315<table width=100% cellspacing=0 border=0><tr>
316<td>Copyright &copy; 2007
317<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
318<td align=right><div align=right>Qt 3.3.8</div>
319</table></div></address></body>
320</html>
Note: See TracBrowser for help on using the repository browser.