source: trunk/doc/src/porting/qt4-tulip.qdoc@ 603

Last change on this file since 603 was 561, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.1 sources.

  • Property svn:eol-style set to native
File size: 8.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \page qt4-tulip.html
44 \title The Tulip Container Classes
45
46 \contentspage {What's New in Qt 4}{Home}
47 \previouspage What's New in Qt 4
48 \nextpage The Interview Framework
49
50 Qt 4 introduces a new set of containers that supersede both the old
51 QCollection pointer-based containers and the newer QTL value-based
52 containers.
53
54 \tableofcontents
55
56 \section1 General Overview
57
58 The Tulip containers are similar to Qt 3's QTL containers
59 (QValueList, QValueVector, QMap), but have the following
60 advantages:
61
62 \list
63 \o The containers provide new iterators with a nicer, less
64 error-prone syntax than STL, inspired by Java's iterators. (The
65 STL-style iterators are still available as a lightweight,
66 STL-compatible alternative.)
67
68 \o The containers have been optimized for minimal code expansion.
69
70 \o An empty container performs no memory allocation, and only
71 requires the same space as a pointer.
72
73 \o Even though they are implicitly shared, they can safely be copied
74 across different threads without formality. There's no need to use
75 \c QDeepCopy.
76 \endlist
77
78 Tulip provides the following sequential containers: QList,
79 QLinkedList, QVector, QStack, and QQueue. For most
80 applications, QList is the best type to use. Although it is
81 implemented as an array-list, it provides very fast prepends and
82 appends. If you really need a linked-list, use QLinkedList; if you
83 want your items to occupy consecutive memory locations, use QVector.
84 QStack and QQueue are convenience classes that provide LIFO and
85 FIFO semantics.
86
87 Tulip also provides these associative containers: QMap,
88 QMultiMap, QHash, QMultiHash, and QSet. The "Multi" containers
89 conveniently support multiple values associated with a single
90 key. The "Hash" containers provide faster lookup by using a hash
91 function instead of a binary search on a sorted set.
92
93 The Tulip containers support the \l foreach keyword, a Qt-specific
94 addition to the C++ language that is implemented using the standard
95 C++ preprocessor. The syntax is:
96
97 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 0
98
99 Example:
100
101 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 1
102
103 The iterator variable can also be defined outside the loop. For
104 example:
105
106 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 2
107
108 Just like standard \c for loops, foreach supports braces, \c
109 break, \c continue, and nested loops. Qt makes a copy of the
110 container when it enters the loop. If you modify the container as
111 you are iterating, that won't affect the loop.
112
113 For details about the new containers, see the
114 \l{Generic Containers} and \l{Generic Algorithms} overview documents.
115
116 In addition to the new containers, considerable work has also gone into
117 QByteArray and QString. The Qt 3 QCString class has been
118 merged with QByteArray. The new QByteArray automatically provides
119 a '\0' terminator after the last character. For example, the byte array
120 of size 5 containing "abcde" has a null byte at position 5 (one past
121 the end). This solves all the typical problems that occurred in Qt 3
122 with conversions between QByteArray and QCString.
123
124 To avoid crashes, QByteArray::data() never returns a null
125 pointer. Furthermore, the distinction between null and empty
126 strings has been watered down so that \c{QByteArray() ==
127 QByteArray("")} and \c{QString() == QString("")}.
128
129 \section1 Examples
130
131 The first group of examples show how to use the new Java-style
132 iterators. The main difference between the Java-style iterators and the
133 STL-style iterators is that the Java-style ones point between items (or
134 before the first item, or after the last item), whereas the STL ones
135 point at an item (or past the last item). One advantage of the
136 Java-style iterators is that iterating forward and backward are
137 symmetric operations.
138
139 Traversing a container using a Java-style iterator:
140
141 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 3
142
143 Modifying items using a Java-style iterator:
144
145 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 4
146
147 Removing items using a Java-style iterator:
148
149 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 5
150
151 Iterating over items with a particular value using STL-style vs.
152 Java-style iterators:
153
154 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 6
155
156 Modifying and removing items using STL-style vs. Java-style
157 iterators:
158
159 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 7
160
161 The next group of examples show the API of the container classes
162 themselves. The API is similar to the QTL classes of Qt 3, but is nicer
163 in many respects.
164
165 Iterating over a QList using an index (which is fast even for large
166 lists, because QList is implemented as an array-list):
167
168 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 8
169
170 Retrieving a value from a map, using a default value if the key
171 doesn't exist:
172
173 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 9
174
175 Getting all the values for a particular key in a QMultiMap or QMultiHash:
176
177 \snippet doc/src/snippets/code/doc_src_qt4-tulip.qdoc 10
178
179 \section1 Comparison with Qt 3
180
181 Tulip containers are value based. If you want to store a list where
182 each item is a QWidget *, use QList<QWidget *>.
183
184 The new containers do not support auto-delete. In practice, we
185 discovered that the only case where auto-delete proved worthwhile was
186 when the data really should be stored as a value rather than as a
187 pointer (e.g., QList<int> rather than QList<int *>). If you need
188 to delete all the items in a container, use qDeleteAll().
189
190 If you use QValueList in Qt 3, you can replace it with either
191 QList or QLinkedList in Qt 4. In most cases, QList is the best
192 choice: It is typically faster, results in less code in your
193 executable, and requires less memory. However, QLinkedList's
194 iterators provide stronger guarantees, and only QLinkedList provides
195 constant-time insertions in the middle, which can make a difference for
196 lists with thousands of items.
197
198 If you use QValueVector or QMap in Qt 3, the corresponding Qt 4
199 classes (QVector, QMap) are very similar to use.
200*/
Note: See TracBrowser for help on using the repository browser.