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 */