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
|
/****************************************************************************
**
** Qt collection classes documentation
**
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file. Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/
/*!
\defgroup collection
\title Collection Classes
\keyword collection classes
\keyword persistent data
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.
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 \link
qt-template-lib.html Qt Template Library\endlink documentation for
details.
The value-based collections are:
\list
\i \l QValueList, a value-based list.
\i \l QValueVector, a value-based vector.
\i \l QValueStack, a value-based stack.
\i \l QMap, a value-based dictionary (associative array).
\endlist
The pointer-based collections are:
\list
\i \l QCache and \l QIntCache, LRU (least recently used) caches.
\i \l QDict, \l QIntDict and \l QPtrDict dictionaries.
\i \l QPtrList, a doubly linked list.
\i \l QPtrQueue, a FIFO (first in, first out) queue.
\i \l QPtrStack, a LIFO (last in, first out) stack.
\i \l QPtrVector, a vector.
\endlist
\l QMemArray 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.
Some of these classes have corresponding iterators. An iterator
is a class for traversing the items in a collection:
\list
\i \link QCacheIterator QCacheIterator\endlink and
\link QIntCacheIterator QIntCacheIterator\endlink
\i \link QDictIterator QDictIterator\endlink,
\link QIntDictIterator QIntDictIterator\endlink, and
\link QPtrDictIterator QPtrDictIterator\endlink
\i \link QPtrListIterator QPtrListIterator\endlink
\i \link QValueListIterator QValueListIterator\endlink, and
\link QValueListConstIterator QValueListConstIterator\endlink
\i \link QMapIterator QMapIterator\endlink, and
\link QMapConstIterator QMapConstIterator\endlink
\endlist
The value-based collections plus algorithms operating on them are
grouped together in the \link qt-template-lib.html Qt Template
Library\endlink; see also the \link ntqtl.html Qt Template
Library Classes\endlink.
The rest of this page dicusses the pointer-based containers.
\section1 Architecture of the pointer-based containers
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.
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.
\section1 A QPtrList Example
This example shows how to store Employee items in a list and prints
them out in reverse order:
\code
#include <ntqptrlist.h>
#include <ntqstring.h>
#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:
QString n;
int s;
};
int main()
{
QPtrList<Employee> list; // list of pointers to Employee
list.setAutoDelete( TRUE ); // delete items when they are removed
list.append( new Employee("Bill", 50000) );
list.append( new Employee("Steve",80000) );
list.append( new Employee("Ron", 60000) );
QPtrListIterator<Employee> it(list); // iterator for employee list
for ( it.toLast(); it.current(); --it) ) {
Employee *emp = it.current();
printf( "%s earns %d\n", emp->name(), emp->salary() );
}
return 0;
}
\endcode
Program output:
\code
Ron earns 60000
Steve earns 80000
Bill earns 50000
\endcode
\section1 Managing Collection Items
All pointer-based collections inherit the \l QPtrCollection base class.
This class only knows about the number of items in the collection and
the deletion strategy.
By default, items in a collection are not deleted when they are
removed from the collection. The \l QPtrCollection::setAutoDelete()
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.
When inserting an item into a collection, only the pointer is copied,
not the item itself. This is called a shallow copy. It is possible to
make the collection copy all of the item's data (known as a deep copy)
when an item is inserted. All collection functions that insert an
item call the virtual function \l QPtrCollection::newItem() for the item
to be inserted. Inherit a collection and reimplement it if you want
to have deep copies in your collection.
When removing an item from a list, the virtual function
\l{QPtrCollection::deleteItem()} is called. The default implementation
in all collection classes deletes the item if auto-deletion is
enabled.
\section1 Usage
A pointer-based collection class, such as QPtrList\<type\>, defines a
collection of \e pointers to \e type objects. The pointer (*) is
implicit.
We discuss \l QPtrList here, but the same techniques apply to all
pointer-based collection classes and all collection class iterators.
Template instantiation:
\code
QPtrList<Employee> list; // wherever the list is used
\endcode
The item's class or type, Employee in our example, must be defined prior
to the list definition.
\code
// Does not work: Employee is not defined
class Employee;
QPtrList<Employee> list;
// This works: Employee is defined before it is used
class Employee {
...
};
QPtrList<Employee> list;
\endcode
\section1 Iterators
Although \l QPtrList has member functions to traverse the list, it can
often be better to make use of an iterator. \l QPtrListIterator is very
safe and can traverse lists that are being modified at the same time.
Multiple iterators can work independently on the same collection.
A QPtrList 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.
The \l QDict and \l QCache collections have no traversal functions. To
traverse these collections, you must use \l QDictIterator or \l
QCacheIterator.
\section1 Predefined Collections
Qt has the following predefined collection classes:
\list
\i String lists: \l QStrList, \l QStrIList (\l ntqstrlist.h) and
\l QStringList (\l ntqstringlist.h)
\i String vectors: QStrVec and QStrIVec (ntqstrvec.h); these are obsolete
\endlist
In almost all cases you would choose \l QStringList, a value
list of implicitly shared QString Unicode strings. QPtrStrList and
QPtrStrIList store only char pointers, not the strings themselves.
\section1 List of Pointer-based Collection Classes and Related
Iterator Classes
*/
|
