source: trunk/doc/html/collection.html

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

reference documentation added
File size: 13.9 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/collect.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Collection Classes</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>Collection Classes</h1>
33
34
35
36<p> <!-- index collection classes --><a name="collection-classes"></a><!-- index persistent data --><a name="persistent-data"></a>
37<p> A collection class is a container which holds a number of items in a
38data structure and provides various operations to manipulate the
39contents of the collection, such as insert item, remove item, find
40item, etc.
41<p> Qt has several value-based and several pointer-based collection
42classes. The pointer-based collection classes work with pointers to
43items, while the value-based classes store copies of their items. The
44value-based collections are very similar to STL container classes, and
45can be used with STL algorithms and containers. See the <a href="qt-template-lib.html">Qt Template Library</a> documentation for
46details.
47<p> The value-based collections are:
48<ul>
49<li> <a href="qvaluelist.html">QValueList</a>, a value-based list.
50<li> <a href="qvaluevector.html">QValueVector</a>, a value-based vector.
51<li> <a href="qvaluestack.html">QValueStack</a>, a value-based stack.
52<li> <a href="qmap.html">QMap</a>, a value-based dictionary (associative array).
53</ul>
54<p> The pointer-based collections are:
55<ul>
56<li> <a href="qcache.html">QCache</a> and <a href="qintcache.html">QIntCache</a>, LRU (least recently used) caches.
57<li> <a href="qdict.html">QDict</a>, <a href="qintdict.html">QIntDict</a> and <a href="qptrdict.html">QPtrDict</a> dictionaries.
58<li> <a href="qptrlist.html">QPtrList</a>, a doubly linked list.
59<li> <a href="qptrqueue.html">QPtrQueue</a>, a FIFO (first in, first out) queue.
60<li> <a href="qptrstack.html">QPtrStack</a>, a LIFO (last in, first out) stack.
61<li> <a href="qptrvector.html">QPtrVector</a>, a vector.
62</ul>
63<p> <a href="qmemarray.html">QMemArray</a> is exceptional; it is neither pointer nor value based,
64but memory based. For maximum efficiency with the simple data types
65usually used in arrays, it uses bitwise operations to copy and compare
66array elements.
67<p> Some of these classes have corresponding iterators. An iterator
68is a class for traversing the items in a collection:
69<ul>
70<li> <a href="qcacheiterator.html">QCacheIterator</a> and
71<a href="qintcacheiterator.html">QIntCacheIterator</a>
72<li> <a href="qdictiterator.html">QDictIterator</a>,
73<a href="qintdictiterator.html">QIntDictIterator</a>, and
74<a href="qptrdictiterator.html">QPtrDictIterator</a>
75<li> <a href="qptrlistiterator.html">QPtrListIterator</a>
76<li> <a href="qvaluelistiterator.html">QValueListIterator</a>, and
77<a href="qvaluelistconstiterator.html">QValueListConstIterator</a>
78<li> <a href="qmapiterator.html">QMapIterator</a>, and
79<a href="qmapconstiterator.html">QMapConstIterator</a>
80</ul>
81<p> The value-based collections plus algorithms operating on them are
82grouped together in the <a href="qt-template-lib.html">Qt Template
83Library</a>; see also the <a href="qtl.html">Qt Template
84Library Classes</a>.
85<p> The rest of this page dicusses the pointer-based containers.
86<p> <h2> Architecture of the pointer-based containers
87</h2>
88<a name="1"></a><p> There are four internal base classes for the pointer-based
89containers (QGCache, QGDict, QGList and QGVector) that operate on
90void pointers. A thin template layer implements the actual
91collections by casting item pointers to and from void pointers.
92<p> This strategy allows Qt's templates to be very economical on space
93(instantiating one of these templates adds only inlinable calls to
94the base classes), without hurting performance.
95<p> <h2> A <a href="qptrlist.html">QPtrList</a> Example
96</h2>
97<a name="2"></a><p> This example shows how to store Employee items in a list and prints
98them out in reverse order:
99<p> <pre>
100 #include &lt;<a href="qptrlist-h.html">qptrlist.h</a>&gt;
101 #include &lt;<a href="qstring-h.html">qstring.h</a>&gt;
102 #include &lt;stdio.h&gt;
103
104 class Employee
105 {
106 public:
107 Employee( const char *name, int salary ) { n=name; s=salary; }
108 const char *name() const { return n; }
109 int salary() const { return s; }
110 private:
111 <a href="qstring.html">QString</a> n;
112 int s;
113 };
114
115 int main()
116 {
117 <a href="qptrlist.html">QPtrList</a>&lt;Employee&gt; list; // list of pointers to Employee
118 list.<a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>( TRUE ); // delete items when they are removed
119
120 list.<a href="qptrlist.html#append">append</a>( new Employee("Bill", 50000) );
121 list.<a href="qptrlist.html#append">append</a>( new Employee("Steve",80000) );
122 list.<a href="qptrlist.html#append">append</a>( new Employee("Ron", 60000) );
123
124 <a href="qptrlistiterator.html">QPtrListIterator</a>&lt;Employee&gt; it(list); // iterator for employee list
125 for ( it.<a href="qptrlistiterator.html#toLast">toLast</a>(); it.<a href="qptrlistiterator.html#current">current</a>(); --it) ) {
126 Employee *emp = it.<a href="qptrlistiterator.html#current">current</a>();
127 printf( "%s earns %d\n", emp-&gt;name(), emp-&gt;salary() );
128 }
129
130 return 0;
131 }
132</pre>
133
134<p> Program output:
135<pre>
136 Ron earns 60000
137 Steve earns 80000
138 Bill earns 50000
139</pre>
140
141<p> <h2> Managing Collection Items
142</h2>
143<a name="3"></a><p> All pointer-based collections inherit the <a href="qptrcollection.html">QPtrCollection</a> base class.
144This class only knows about the number of items in the collection and
145the deletion strategy.
146<p> By default, items in a collection are not deleted when they are
147removed from the collection. The <a href="qptrcollection.html#setAutoDelete">QPtrCollection::setAutoDelete</a>()
148function specifies the deletion strategy. In the list example, we
149enable auto-deletion to make the list delete the items when they are
150removed from the list.
151<p> When inserting an item into a collection, only the pointer is copied,
152not the item itself. This is called a <a href="shclass.html#shallow-copy">shallow copy</a>. It is possible to
153make the collection copy all of the item's data (known as a <a href="shclass.html#deep-copy">deep copy</a>)
154when an item is inserted. All collection functions that insert an
155item call the virtual function <a href="qptrcollection.html#newItem">QPtrCollection::newItem</a>() for the item
156to be inserted. Inherit a collection and reimplement it if you want
157to have deep copies in your collection.
158<p> When removing an item from a list, the virtual function
159<a href="qptrcollection.html#deleteItem">QPtrCollection::deleteItem</a>() is called. The default implementation
160in all collection classes deletes the item if auto-deletion is
161enabled.
162<p> <h2> Usage
163</h2>
164<a name="4"></a><p> A pointer-based collection class, such as <a href="qptrlist.html">QPtrList</a>&lt;type&gt;, defines a
165collection of <em>pointers</em> to <em>type</em> objects. The pointer (*) is
166implicit.
167<p> We discuss <a href="qptrlist.html">QPtrList</a> here, but the same techniques apply to all
168pointer-based collection classes and all collection class iterators.
169<p> Template instantiation:
170<pre>
171 <a href="qptrlist.html">QPtrList</a>&lt;Employee&gt; list; // wherever the list is used
172</pre>
173
174<p> The item's class or type, Employee in our example, must be defined prior
175to the list definition.
176<p> <pre>
177 // Does not work: Employee is not defined
178 class Employee;
179 <a href="qptrlist.html">QPtrList</a>&lt;Employee&gt; list;
180
181 // This works: Employee is defined before it is used
182 class Employee {
183 ...
184 };
185 <a href="qptrlist.html">QPtrList</a>&lt;Employee&gt; list;
186</pre>
187
188<p> <h2> Iterators
189</h2>
190<a name="5"></a><p> Although <a href="qptrlist.html">QPtrList</a> has member functions to traverse the list, it can
191often be better to make use of an iterator. <a href="qptrlistiterator.html">QPtrListIterator</a> is very
192safe and can traverse lists that are being modified at the same time.
193Multiple iterators can work independently on the same collection.
194<p> A <a href="qptrlist.html">QPtrList</a> has an internal list of all the iterators that are
195currently operating on it. When a list entry is removed, the list
196updates all iterators accordingly.
197<p> The <a href="qdict.html">QDict</a> and <a href="qcache.html">QCache</a> collections have no traversal functions. To
198traverse these collections, you must use <a href="qdictiterator.html">QDictIterator</a> or <a href="qcacheiterator.html">QCacheIterator</a>.
199<p> <h2> Predefined Collections
200</h2>
201<a name="6"></a><p> Qt has the following predefined collection classes:
202<ul>
203<li> String lists: <a href="qstrlist.html">QStrList</a>, <a href="qstrilist.html">QStrIList</a> (<a href="qstrlist-h.html">qstrlist.h</a>) and
204<a href="qstringlist.html">QStringList</a> (<a href="qstringlist-h.html">qstringlist.h</a>)
205<li> String vectors: QStrVec and QStrIVec (qstrvec.h); these are obsolete
206</ul>
207<p> In almost all cases you would choose <a href="qstringlist.html">QStringList</a>, a value
208list of <a href="shclass.html#implicitly-shared">implicitly shared</a> <a href="qstring.html">QString</a> Unicode strings. QPtrStrList and
209QPtrStrIList store only char pointers, not the strings themselves.
210<p> <h2> List of Pointer-based Collection Classes and Related
211Iterator Classes
212</h2>
213<a name="7"></a><p>
214<p><table width="100%">
215<tr bgcolor=#f0f0f0><td><b><a href="qasciicache.html">QAsciiCache</a></b><td>Template class that provides a cache based on char* keys
216<tr bgcolor=#f0f0f0><td><b><a href="qasciicacheiterator.html">QAsciiCacheIterator</a></b><td>Iterator for QAsciiCache collections
217<tr bgcolor=#f0f0f0><td><b><a href="qasciidict.html">QAsciiDict</a></b><td>Template class that provides a dictionary based on char* keys
218<tr bgcolor=#f0f0f0><td><b><a href="qasciidictiterator.html">QAsciiDictIterator</a></b><td>Iterator for QAsciiDict collections
219<tr bgcolor=#f0f0f0><td><b><a href="qbitarray.html">QBitArray</a></b><td>Array of bits
220<tr bgcolor=#f0f0f0><td><b><a href="qbitval.html">QBitVal</a></b><td>Internal class, used with QBitArray
221<tr bgcolor=#f0f0f0><td><b><a href="qbuffer.html">QBuffer</a></b><td>I/O device that operates on a QByteArray
222<tr bgcolor=#f0f0f0><td><b><a href="qbytearray.html">QByteArray</a></b><td>Array of bytes
223<tr bgcolor=#f0f0f0><td><b><a href="qcache.html">QCache</a></b><td>Template class that provides a cache based on QString keys
224<tr bgcolor=#f0f0f0><td><b><a href="qcacheiterator.html">QCacheIterator</a></b><td>Iterator for QCache collections
225<tr bgcolor=#f0f0f0><td><b><a href="qcstring.html">QCString</a></b><td>Abstraction of the classic C zero-terminated char array (char *)
226<tr bgcolor=#f0f0f0><td><b><a href="qdict.html">QDict</a></b><td>Template class that provides a dictionary based on QString keys
227<tr bgcolor=#f0f0f0><td><b><a href="qdictiterator.html">QDictIterator</a></b><td>Iterator for QDict collections
228<tr bgcolor=#f0f0f0><td><b><a href="qintcache.html">QIntCache</a></b><td>Template class that provides a cache based on long keys
229<tr bgcolor=#f0f0f0><td><b><a href="qintcacheiterator.html">QIntCacheIterator</a></b><td>Iterator for QIntCache collections
230<tr bgcolor=#f0f0f0><td><b><a href="qintdict.html">QIntDict</a></b><td>Template class that provides a dictionary based on long keys
231<tr bgcolor=#f0f0f0><td><b><a href="qintdictiterator.html">QIntDictIterator</a></b><td>Iterator for QIntDict collections
232<tr bgcolor=#f0f0f0><td><b><a href="qobjectlist.html">QObjectList</a></b><td>QPtrList of QObjects
233<tr bgcolor=#f0f0f0><td><b><a href="qobjectlistiterator.html">QObjectListIterator</a></b><td>Iterator for QObjectLists
234<tr bgcolor=#f0f0f0><td><b><a href="qptrcollection.html">QPtrCollection</a></b><td>The base class of most pointer-based Qt collections
235<tr bgcolor=#f0f0f0><td><b><a href="qptrdict.html">QPtrDict</a></b><td>Template class that provides a dictionary based on void* keys
236<tr bgcolor=#f0f0f0><td><b><a href="qptrdictiterator.html">QPtrDictIterator</a></b><td>Iterator for QPtrDict collections
237<tr bgcolor=#f0f0f0><td><b><a href="qptrlist.html">QPtrList</a></b><td>Template class that provides a list
238<tr bgcolor=#f0f0f0><td><b><a href="qptrlistiterator.html">QPtrListIterator</a></b><td>Iterator for QPtrList collections
239<tr bgcolor=#f0f0f0><td><b><a href="qptrqueue.html">QPtrQueue</a></b><td>Template class that provides a queue
240<tr bgcolor=#f0f0f0><td><b><a href="qstrilist.html">QStrIList</a></b><td>Doubly-linked list of char* with case-insensitive comparison
241<tr bgcolor=#f0f0f0><td><b><a href="qstrlist.html">QStrList</a></b><td>Doubly-linked list of char*
242</table>
243<!-- eof -->
244<p><address><hr><div align=center>
245<table width=100% cellspacing=0 border=0><tr>
246<td>Copyright &copy; 2007
247<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
248<td align=right><div align=right>Qt 3.3.8</div>
249</table></div></address></body>
250</html>
Note: See TracBrowser for help on using the repository browser.