<!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>TQt 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>TQt Template Library</h1>
<p>
<p> The TQt Template Library (TQTL) is a set of templates that provide
object containers. If a suitable STL implementation is not available
on all your target platforms, the TQTL 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 TQTL classes' naming conventions are consistent with the other TQt
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 TQTL only contains the most important features
of the STL container API. Compared with the STL, TQTL 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="ntqptrcollection.html">TQPtrCollection</a> and friends, all of which operate on pointers
rather than values. This applies, for example, to all classes derived
from <a href="ntqobject.html">TQObject</a>. A <a href="ntqobject.html">TQObject</a> does not have a copy constructor, so using
it as value is impossible. You may choose to store pointers to
TQObjects in a <a href="ntqvaluelist.html">TQValueList</a>, but using <a href="ntqptrlist.html">TQPtrList</a> directly seems to be the
better choice for this kind of application domain. TQPtrList, like all
other TQPtrCollection 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 TQt 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="ntqcstring.html#operator-lt-2">operator<</a>() for
your data's class.
<p> Good candidates for value based classes are <a href="ntqrect.html">TQRect</a>, <a href="ntqpoint.html">TQPoint</a>, <a href="ntqsize.html">TQSize</a>,
<a href="ntqstring.html">TQString</a> and all simple C++ types, such as int, bool or double.
<p> The TQt Template Library is designed for speed. Iterators are extremely
fast. To achieve this performance, less error checking is done than in
the <a href="ntqptrcollection.html">TQPtrCollection</a> based containers. A TQTL 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 TQt 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 TQValueList<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 TQMap<TQString,TQString> 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 TQValueVector<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 TQt 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 TQValueList<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="ntqcstring.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> tqSwap()
</h3>
<a name="2-2"></a><p> tqSwap() exchanges the values of two variables:
<pre>
<a href="ntqstring.html">TQString</a> second( "Einstein" );
<a href="ntqstring.html">TQString</a> name( "Albert" );
tqSwap( second, name );
</pre>
<p> <a name="qCount"></a>
<h3> tqCount()
</h3>
<a name="2-3"></a><p> The tqCount() template function counts the number of occurrences of a
value within a container. For example:
<pre>
<a href="ntqvaluelist.html">TQValueList</a><int> list;
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 2 );
int c = 0;
tqCount( list.<a href="ntqvaluelist.html#begin">begin</a>(), list.<a href="ntqvaluelist.html#end">end</a>(), 1, c ); // c == 3
</pre>
<p> <a name="qFind"></a>
<h3> tqFind()
</h3>
<a name="2-4"></a><p> The tqFind() template function finds the first occurrence of a value
within a container. For example:
<pre>
<a href="ntqvaluelist.html">TQValueList</a><int> list;
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 1 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 2 );
<a href="qvaluelistiterator.html">TQValueListIterator</a><int> it = tqFind( list.<a href="ntqvaluelist.html#begin">begin</a>(), list.<a href="ntqvaluelist.html#end">end</a>(), 2 );
</pre>
<p> <a name="qFill"></a>
<h3> tqFill()
</h3>
<a name="2-5"></a><p> The tqFill() template function fills a range with copies of a value.
For example:
<pre>
<a href="ntqvaluevector.html">TQValueVector</a><int> vec(3);
tqFill( vec.<a href="ntqvaluevector.html#begin">begin</a>(), vec.<a href="ntqvaluevector.html#end">end</a>(), 99 ); // vec contains 99, 99, 99
</pre>
<p> <a name="qEqual"></a>
<h3> tqEqual()
</h3>
<a name="2-6"></a><p> The tqEqual() 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="ntqvaluevector.html">TQValueVector</a><int> v1(3);
v1[0] = 1;
v1[2] = 2;
v1[3] = 3;
<a href="ntqvaluevector.html">TQValueVector</a><int> v2(5);
v2[0] = 1;
v2[2] = 2;
v2[3] = 3;
v2[4] = 4;
v2[5] = 5;
bool b = tqEqual( v1.<a href="ntqvaluevector.html#begin">begin</a>(), v2.<a href="ntqvaluevector.html#end">end</a>(), v2.<a href="ntqvaluevector.html#begin">begin</a>() );
// b == TRUE
</pre>
<p> <a name="qCopy"></a>
<h3> tqCopy()
</h3>
<a name="2-7"></a><p> The tqCopy() template function copies a range of elements to an
OutputIterator, in this case a TQTextOStreamIterator:
<pre>
<a href="ntqvaluelist.html">TQValueList</a><int> list;
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 100 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 200 );
list.<a href="ntqvaluelist.html#push_back">push_back</a>( 300 );
<a href="qtextostream.html">TQTextOStream</a> str( stdout );
tqCopy( list.<a href="ntqvaluelist.html#begin">begin</a>(), list.<a href="ntqvaluelist.html#end">end</a>(), TQTextOStreamIterator(str) );
</pre>
<p>
<p> <a name="qCopyBackward"></a>
<h3> tqCopyBackward()
</h3>
<a name="2-8"></a><p> The tqCopyBackward() template function copies a container or a slice of
a container to an OutputIterator, but in reverse order, for example:
<pre>
<a href="ntqvaluevector.html">TQValueVector</a><int> vec(3);
vec.<a href="ntqvaluevector.html#push_back">push_back</a>( 100 );
vec.<a href="ntqvaluevector.html#push_back">push_back</a>( 200 );
vec.<a href="ntqvaluevector.html#push_back">push_back</a>( 300 );
<a href="ntqvaluevector.html">TQValueVector</a><int> another;
tqCopyBackward( vec.<a href="ntqvaluevector.html#begin">begin</a>(), vec.<a href="ntqvaluevector.html#end">end</a>(), another.<a href="ntqvaluevector.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> TQTL Iterators
</h3>
<a name="2-9"></a><p> You can use any TQt 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="ntqstringlist.html">TQStringList</a> list1, list2;
list1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
list2 << "Torben" << "Matthias";
tqCopy( list2.begin(), list2.end(), list1.<a href="ntqvaluelist.html#begin">begin</a>() );
<a href="ntqvaluevector.html">TQValueVector</a><TQString> vec( list1.<a href="ntqvaluelist.html#size">size</a>(), "Dave" );
tqCopy( list2.begin(), list2.end(), vec.<a href="ntqvaluevector.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 tqCopy():
<p> <pre>
int arr[] = { 100, 200, 300 };
<a href="qtextostream.html">TQTextOStream</a> str( stdout );
tqCopy( arr, arr + 3, TQTextOStreamIterator( 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="ntqdatastream.html">TQDataStream</a> str(...);
<a href="ntqvaluelist.html">TQValueList</a><TQRect> list;
// ... fill the list here
str << list;
</pre>
<p> The container can be read in again with:
<p> <pre>
<a href="ntqvaluelist.html">TQValueList</a><TQRect> list;
str >> list;
</pre>
<p> The same applies to <a href="ntqstringlist.html">TQStringList</a>, <a href="ntqvaluestack.html">TQValueStack</a> and <a href="ntqmap.html">TQMap</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>TQt 3.3.8</div>
</table></div></address></body>
</html>