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