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

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

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