You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
321 lines
14 KiB
321 lines
14 KiB
13 years ago
|
<!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="qptrcollection.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="qobject.html">TQObject</a>. A <a href="qobject.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="qvaluelist.html">TQValueList</a>, but using <a href="qptrlist.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 retquire 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">TQRect</a>, <a href="qpoint.html">TQPoint</a>, <a href="qsize.html">TQSize</a>,
|
||
|
|
<a href="qstring.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="qptrcollection.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 retquired
|
||
|
|
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="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">TQString</a> second( "Einstein" );
|
||
|
|
<a href="qstring.html">TQString</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">TQValueList</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">TQValueList</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">TQValueListIterator</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">TQValueVector</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">TQValueVector</a><int> v1(3);
|
||
|
|
v1[0] = 1;
|
||
|
|
v1[2] = 2;
|
||
|
|
v1[3] = 3;
|
||
|
|
|
||
|
|
<a href="qvaluevector.html">TQValueVector</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 TQTextOStreamIterator:
|
||
|
|
<pre>
|
||
|
|
<a href="qvaluelist.html">TQValueList</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">TQTextOStream</a> str( stdout );
|
||
|
|
qCopy( list.<a href="qvaluelist.html#begin">begin</a>(), list.<a href="qvaluelist.html#end">end</a>(), TQTextOStreamIterator(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">TQValueVector</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">TQValueVector</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> 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="qstringlist.html">TQStringList</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">TQValueVector</a><TQString> 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">TQTextOStream</a> str( stdout );
|
||
|
|
qCopy( 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="qdatastream.html">TQDataStream</a> str(...);
|
||
|
|
<a href="qvaluelist.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="qvaluelist.html">TQValueList</a><TQRect> list;
|
||
|
|
str >> list;
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> The same applies to <a href="qstringlist.html">TQStringList</a>, <a href="qvaluestack.html">TQValueStack</a> and <a href="qmap.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>
|