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
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt4-tulip.html
\title The Tulip Container Classes
\contentspage {What's New in Qt 4}{Home}
\previouspage What's New in Qt 4
\nextpage The Interview Framework
Qt 4 introduces a new set of containers that supersede both the old
QCollection pointer-based containers and the newer QTL value-based
containers.
\tableofcontents
\section1 General Overview
The Tulip containers are similar to Qt 3's QTL containers
(QValueList, QValueVector, QMap), but have the following
advantages:
\list
\o The containers provide new iterators with a nicer, less
error-prone syntax than STL, inspired by Java's iterators. (The
STL-style iterators are still available as a lightweight,
STL-compatible alternative.)
\o The containers have been optimized for minimal code expansion.
\o An empty container performs no memory allocation, and only
requires the same space as a pointer.
\o Even though they are implicitly shared, they can safely be copied
across different threads without formality. There's no need to use
\c QDeepCopy.
\endlist
Tulip provides the following sequential containers: QList,
QLinkedList, QVector, QStack, and QQueue. For most
applications, QList is the best type to use. Although it is
implemented as an array-list, it provides very fast prepends and
appends. If you really need a linked-list, use QLinkedList; if you
want your items to occupy consecutive memory locations, use QVector.
QStack and QQueue are convenience classes that provide LIFO and
FIFO semantics.
Tulip also provides these associative containers: QMap,
QMultiMap, QHash, QMultiHash, and QSet. The "Multi" containers
conveniently support multiple values associated with a single
key. The "Hash" containers provide faster lookup by using a hash
function instead of a binary search on a sorted set.
The Tulip containers support the \l foreach keyword, a Qt-specific
addition to the C++ language that is implemented using the standard
C++ preprocessor. The syntax is:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 0
Example:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 1
The iterator variable can also be defined outside the loop. For
example:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 2
Just like standard \c for loops, foreach supports braces, \c
break, \c continue, and nested loops. Qt makes a copy of the
container when it enters the loop. If you modify the container as
you are iterating, that won't affect the loop.
For details about the new containers, see the
\l{Generic Containers} and \l{Generic Algorithms} overview documents.
In addition to the new containers, considerable work has also gone into
QByteArray and QString. The Qt 3 QCString class has been
merged with QByteArray. The new QByteArray automatically provides
a '\0' terminator after the last character. For example, the byte array
of size 5 containing "abcde" has a null byte at position 5 (one past
the end). This solves all the typical problems that occurred in Qt 3
with conversions between QByteArray and QCString.
To avoid crashes, QByteArray::data() never returns a null
pointer. Furthermore, the distinction between null and empty
strings has been watered down so that \c{QByteArray() ==
QByteArray("")} and \c{QString() == QString("")}.
\section1 Examples
The first group of examples show how to use the new Java-style
iterators. The main difference between the Java-style iterators and the
STL-style iterators is that the Java-style ones point between items (or
before the first item, or after the last item), whereas the STL ones
point at an item (or past the last item). One advantage of the
Java-style iterators is that iterating forward and backward are
symmetric operations.
Traversing a container using a Java-style iterator:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 3
Modifying items using a Java-style iterator:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 4
Removing items using a Java-style iterator:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 5
Iterating over items with a particular value using STL-style vs.
Java-style iterators:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 6
Modifying and removing items using STL-style vs. Java-style
iterators:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 7
The next group of examples show the API of the container classes
themselves. The API is similar to the QTL classes of Qt 3, but is nicer
in many respects.
Iterating over a QList using an index (which is fast even for large
lists, because QList is implemented as an array-list):
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 8
Retrieving a value from a map, using a default value if the key
doesn't exist:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 9
Getting all the values for a particular key in a QMultiMap or QMultiHash:
\snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 10
\section1 Comparison with Qt 3
Tulip containers are value based. If you want to store a list where
each item is a QWidget *, use QList<QWidget *>.
The new containers do not support auto-delete. In practice, we
discovered that the only case where auto-delete proved worthwhile was
when the data really should be stored as a value rather than as a
pointer (e.g., QList<int> rather than QList<int *>). If you need
to delete all the items in a container, use qDeleteAll().
If you use QValueList in Qt 3, you can replace it with either
QList or QLinkedList in Qt 4. In most cases, QList is the best
choice: It is typically faster, results in less code in your
executable, and requires less memory. However, QLinkedList's
iterators provide stronger guarantees, and only QLinkedList provides
constant-time insertions in the middle, which can make a difference for
lists with thousands of items.
If you use QValueVector or QMap in Qt 3, the corresponding Qt 4
classes (QVector, QMap) are very similar to use.
*/
|
