diff options
Diffstat (limited to 'doc/html/qt-template-lib.html')
| -rw-r--r-- | doc/html/qt-template-lib.html | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/doc/html/qt-template-lib.html b/doc/html/qt-template-lib.html new file mode 100644 index 0000000..0b10489 --- /dev/null +++ b/doc/html/qt-template-lib.html @@ -0,0 +1,320 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qtl.doc:36 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Qt Template Library</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<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> + + +<p> +<p> The Qt Template Library (QTL) is a set of templates that provide +object containers. If a suitable STL implementation is not available +on all your target platforms, the QTL 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 <a href="#Iterators">iterators</a> and <a href="#Algorithms">algorithms</a>. A container is an object which +contains and manages other objects and provides iterators that allow +the contained objects to be accessed. +<p> The QTL classes' naming conventions are consistent with the other Qt +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 <tt>map</tt> can use the +STL-compatible functions if preferred. +<p> Compared to the STL, the QTL only contains the most important features +of the STL container API. Compared with the STL, QTL has no platform +differences, but is often a little slower and often expands to less +object code. +<p> If you cannot make copies of the objects you want to store you should +use <a href="qptrcollection.html">QPtrCollection</a> and friends, all of which operate on pointers +rather than values. This applies, for example, to all classes derived +from <a href="qobject.html">QObject</a>. A <a href="qobject.html">QObject</a> does not have a copy constructor, so using +it as value is impossible. You may choose to store pointers to +QObjects in a <a href="qvaluelist.html">QValueList</a>, but using <a href="qptrlist.html">QPtrList</a> directly seems to be the +better choice for this kind of application domain. QPtrList, like all +other QPtrCollection based containers, provides far more sanity +checking than a speed-optimized value based container. +<p> If you have objects that implement value semantics, and the STL is not +available on your target platform, the Qt Template Library can be used +instead. Value semantics require at least: +<ul> +<li> a copy constructor; +<li> an assignment operator; +<li> a defaultconstructor, i.e. a constructor that does not take any arguments. +</ul> +<p> Note that a fast copy constructor is absolutely crucial to achieve +good overall performance of the container, since many copy operations +will occur. +<p> If you intend sorting your data you must implement <a href="qcstring.html#operator-lt-2">operator<</a>() for +your data's class. +<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>, +<a href="qstring.html">QString</a> and all simple C++ types, such as int, bool or double. +<p> The Qt Template Library is designed for speed. Iterators are extremely +fast. To achieve this performance, less error checking is done than in +the <a href="qptrcollection.html">QPtrCollection</a> based containers. A QTL 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. +<p> <a name="Iterators"></a> +<h2> Iterators +</h2> +<a name="1"></a><p> The Qt 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. +<p> To iterate over a container, use a loop like this: +<pre> + typedef QValueList<int> List; + List list; + for( List::Iterator it = list.begin(); it != list.end(); ++it ) + printf( "Number is %i\n", *it ); +</pre> + +<p> begin() returns the iterator pointing at the first element, while +end() returns an iterator that points <em>after</em> 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. +<p> The same concept applies to the other container classes: +<pre> + typedef QMap<QString,QString> 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 QValueVector<int> Vector; + Vector vec; + for( Vector::iterator it = vec.begin(); it != vec.end(); ++it ) + printf( "Data=%d\n", *it ); +</pre> + +<p> 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 required +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. +<p> <a name="Algorithms"></a> +<h2> Algorithms +</h2> +<a name="2"></a><p> The Qt 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). +<p> <h3> qHeapSort() +</h3> +<a name="2-1"></a><p> qHeapSort() provides a well known sorting algorithm. You can use it +like this: +<pre> + typedef QValueList<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 ); +</pre> + +<p> 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. +<p> If using your own data types you must implement <a href="qcstring.html#operator-lt-2">operator<</a>() for +your data's class. +<p> Naturally, the sorting templates won't work with const iterators. +<p> <a name="qSwap"></a> +<h3> qSwap() +</h3> +<a name="2-2"></a><p> qSwap() exchanges the values of two variables: +<pre> + <a href="qstring.html">QString</a> second( "Einstein" ); + <a href="qstring.html">QString</a> name( "Albert" ); + qSwap( second, name ); +</pre> + +<p> <a name="qCount"></a> +<h3> qCount() +</h3> +<a name="2-3"></a><p> The qCount() template function counts the number of occurrences of a +value within a container. For example: +<pre> + <a href="qvaluelist.html">QValueList</a><int> list; + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 2 ); + int c = 0; + qCount( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), 1, c ); // c == 3 +</pre> + +<p> <a name="qFind"></a> +<h3> qFind() +</h3> +<a name="2-4"></a><p> The qFind() template function finds the first occurrence of a value +within a container. For example: +<pre> + <a href="qvaluelist.html">QValueList</a><int> list; + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 1 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 2 ); + <a href="qvaluelistiterator.html">QValueListIterator</a><int> it = qFind( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), 2 ); +</pre> + +<p> <a name="qFill"></a> +<h3> qFill() +</h3> +<a name="2-5"></a><p> The qFill() template function fills a range with copies of a value. +For example: +<pre> + <a href="qvaluevector.html">QValueVector</a><int> vec(3); + qFill( vec.<a href="qvaluevector.html#begin">begin</a>(), vec.<a href="qvaluevector.html#end">end</a>(), 99 ); // vec contains 99, 99, 99 +</pre> + +<p> <a name="qEqual"></a> +<h3> qEqual() +</h3> +<a name="2-6"></a><p> 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: +<pre> + <a href="qvaluevector.html">QValueVector</a><int> v1(3); + v1[0] = 1; + v1[2] = 2; + v1[3] = 3; + + <a href="qvaluevector.html">QValueVector</a><int> v2(5); + v2[0] = 1; + v2[2] = 2; + v2[3] = 3; + v2[4] = 4; + v2[5] = 5; + + 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>() ); + // b == TRUE +</pre> + +<p> <a name="qCopy"></a> +<h3> qCopy() +</h3> +<a name="2-7"></a><p> The qCopy() template function copies a range of elements to an +OutputIterator, in this case a QTextOStreamIterator: +<pre> + <a href="qvaluelist.html">QValueList</a><int> list; + list.<a href="qvaluelist.html#push_back">push_back</a>( 100 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 200 ); + list.<a href="qvaluelist.html#push_back">push_back</a>( 300 ); + <a href="qtextostream.html">QTextOStream</a> str( stdout ); + qCopy( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), QTextOStreamIterator(str) ); +</pre> + +<p> +<p> <a name="qCopyBackward"></a> +<h3> qCopyBackward() +</h3> +<a name="2-8"></a><p> The qCopyBackward() template function copies a container or a slice of +a container to an OutputIterator, but in reverse order, for example: +<pre> + <a href="qvaluevector.html">QValueVector</a><int> vec(3); + vec.<a href="qvaluevector.html#push_back">push_back</a>( 100 ); + vec.<a href="qvaluevector.html#push_back">push_back</a>( 200 ); + vec.<a href="qvaluevector.html#push_back">push_back</a>( 300 ); + <a href="qvaluevector.html">QValueVector</a><int> another; + 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>() ); + // 'another' now contains 100, 200, 300 + // however the elements are copied one at a time + // in reverse order (300, 200, then 100) +</pre> + +<p> <h3> QTL Iterators +</h3> +<a name="2-9"></a><p> You can use any Qt 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: +<p> <pre> + <a href="qstringlist.html">QStringList</a> list1, list2; + list1 << "Weis" << "Ettrich" << "Arnt" << "Sue"; + list2 << "Torben" << "Matthias"; + qCopy( list2.begin(), list2.end(), list1.<a href="qvaluelist.html#begin">begin</a>() ); + + <a href="qvaluevector.html">QValueVector</a><QString> vec( list1.<a href="qvaluelist.html#size">size</a>(), "Dave" ); + qCopy( list2.begin(), list2.end(), vec.<a href="qvaluevector.html#begin">begin</a>() ); +</pre> + +<p> 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. +<p> 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(): +<p> <pre> + int arr[] = { 100, 200, 300 }; + <a href="qtextostream.html">QTextOStream</a> str( stdout ); + qCopy( arr, arr + 3, QTextOStreamIterator( str ) ); +</pre> + +<p> <h2> Streaming +</h2> +<a name="3"></a><p> All the containers we've mentioned can be serialized with the +appropriate streaming operators. Here is an example. +<p> <pre> + <a href="qdatastream.html">QDataStream</a> str(...); + <a href="qvaluelist.html">QValueList</a><QRect> list; + // ... fill the list here + str << list; +</pre> + +<p> The container can be read in again with: +<p> <pre> + <a href="qvaluelist.html">QValueList</a><QRect> list; + str >> list; +</pre> + +<p> The same applies to <a href="qstringlist.html">QStringList</a>, <a href="qvaluestack.html">QValueStack</a> and <a href="qmap.html">QMap</a>. + +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |