← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/corelib/tools/qvarlengtharray.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/corelib/tools/qvarlengtharray.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2009 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:LGPL$
 
10
** No Commercial Usage
 
11
** This file contains pre-release code and may not be distributed.
 
12
** You may use this file in accordance with the terms and conditions
 
13
** contained in the Technology Preview License Agreement accompanying
 
14
** this package.
 
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
** If you have questions regarding the use of this file, please contact
 
29
** Nokia at qt-info@nokia.com.
 
30
**
 
31
**
 
32
**
 
33
**
 
34
**
 
35
**
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
/*!
 
43
    \class QVarLengthArray
 
44
    \brief The QVarLengthArray class provides a low-level variable-length array.
 
45
 
 
46
    \ingroup tools
 
47
    \reentrant
 
48
 
 
49
    The C++ language doesn't support variable-length arrays on the stack.
 
50
    For example, the following code won't compile:
 
51
 
 
52
    \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0
 
53
 
 
54
    The alternative is to allocate the array on the heap (with
 
55
    \c{new}):
 
56
 
 
57
    \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1
 
58
 
 
59
    However, if myfunc() is called very frequently from the
 
60
    application's inner loop, heap allocation can be a major source
 
61
    of slowdown.
 
62
 
 
63
    QVarLengthArray is an attempt to work around this gap in the C++
 
64
    language. It allocates a certain number of elements on the stack,
 
65
    and if you resize the array to a larger size, it automatically
 
66
    uses the heap instead. Stack allocation has the advantage that
 
67
    it is much faster than heap allocation.
 
68
 
 
69
    Example:
 
70
    \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2
 
71
 
 
72
    In the example above, QVarLengthArray will preallocate 1024
 
73
    elements on the stack and use them unless \c{n + 1} is greater
 
74
    than 1024. If you omit the second template argument,
 
75
    QVarLengthArray's default of 256 is used.
 
76
 
 
77
    QVarLengthArray's value type must be an \l{assignable data type}.
 
78
    This covers most data types that are commonly used, but the
 
79
    compiler won't let you, for example, store a QWidget as a value;
 
80
    instead, store a QWidget *.
 
81
 
 
82
    QVarLengthArray, like QVector, provides a resizable array data
 
83
    structure. The main differences between the two classes are:
 
84
 
 
85
    \list
 
86
    \o QVarLengthArray's API is much more low-level. It provides no
 
87
       iterators and lacks much of QVector's functionality.
 
88
 
 
89
    \o QVarLengthArray doesn't initialize the memory if the value is
 
90
       a basic type. (QVector always does.)
 
91
 
 
92
    \o QVector uses \l{implicit sharing} as a memory optimization.
 
93
       QVarLengthArray doesn't provide that feature; however, it
 
94
       usually produces slightly better performance due to reduced
 
95
       overhead, especially in tight loops.
 
96
    \endlist
 
97
 
 
98
    In summary, QVarLengthArray is a low-level optimization class
 
99
    that only makes sense in very specific cases. It is used a few
 
100
    places inside Qt and was added to Qt's public API for the
 
101
    convenience of advanced users.
 
102
 
 
103
    \sa QVector, QList, QLinkedList
 
104
*/
 
105
 
 
106
/*! \fn QVarLengthArray::QVarLengthArray(int size)
 
107
 
 
108
    Constructs an array with an initial size of \a size elements.
 
109
 
 
110
    If the value type is a primitive type (e.g., char, int, float) or
 
111
    a pointer type (e.g., QWidget *), the elements are not
 
112
    initialized. For other types, the elements are initialized with a
 
113
    \l{default-constructed value}.
 
114
*/
 
115
 
 
116
/*! \fn QVarLengthArray::~QVarLengthArray()
 
117
 
 
118
    Destroys the array.
 
119
*/
 
120
 
 
121
/*! \fn int QVarLengthArray::size() const
 
122
 
 
123
    Returns the number of elements in the array.
 
124
 
 
125
    \sa isEmpty(), resize()
 
126
*/
 
127
 
 
128
/*! \fn int QVarLengthArray::count() const
 
129
 
 
130
    Same as size().
 
131
 
 
132
    \sa isEmpty(), resize()
 
133
*/
 
134
 
 
135
/*! \fn bool QVarLengthArray::isEmpty() const
 
136
 
 
137
    Returns true if the array has size 0; otherwise returns false.
 
138
 
 
139
    \sa size(), resize()
 
140
*/
 
141
 
 
142
/*! \fn void QVarLengthArray::clear()
 
143
 
 
144
    Removes all the elements from the array.
 
145
 
 
146
    Same as resize(0).
 
147
*/
 
148
 
 
149
/*! \fn void QVarLengthArray::resize(int size)
 
150
 
 
151
    Sets the size of the array to \a size. If \a size is greater than
 
152
    the current size, elements are added to the end. If \a size is
 
153
    less than the current size, elements are removed from the end.
 
154
 
 
155
    If the value type is a primitive type (e.g., char, int, float) or
 
156
    a pointer type (e.g., QWidget *), new elements are not
 
157
    initialized. For other types, the elements are initialized with a
 
158
    \l{default-constructed value}.
 
159
 
 
160
    \sa size()
 
161
*/
 
162
 
 
163
/*! \fn int QVarLengthArray::capacity() const
 
164
 
 
165
    Returns the maximum number of elements that can be stored in the
 
166
    array without forcing a reallocation.
 
167
 
 
168
    The sole purpose of this function is to provide a means of fine
 
169
    tuning QVarLengthArray's memory usage. In general, you will rarely ever
 
170
    need to call this function. If you want to know how many items are
 
171
    in the array, call size().
 
172
 
 
173
    \sa reserve()
 
174
*/
 
175
 
 
176
/*! \fn void QVarLengthArray::reserve(int size)
 
177
 
 
178
    Attempts to allocate memory for at least \a size elements. If you
 
179
    know in advance how large the array can get, you can call this
 
180
    function and if you call resize() often, you are likely to get
 
181
    better performance. If \a size is an underestimate, the worst
 
182
    that will happen is that the QVarLengthArray will be a bit
 
183
    slower.
 
184
 
 
185
    The sole purpose of this function is to provide a means of fine
 
186
    tuning QVarLengthArray's memory usage. In general, you will
 
187
    rarely ever need to call this function. If you want to change the
 
188
    size of the array, call resize().
 
189
 
 
190
    \sa capacity()
 
191
*/
 
192
 
 
193
/*! \fn T &QVarLengthArray::operator[](int i)
 
194
 
 
195
    Returns a reference to the item at index position \a i.
 
196
 
 
197
    \a i must be a valid index position in the array (i.e., 0 <= \a i
 
198
    < size()).
 
199
 
 
200
    \sa data()
 
201
*/
 
202
 
 
203
/*! \fn const T &QVarLengthArray::operator[](int i) const
 
204
 
 
205
    \overload
 
206
*/
 
207
 
 
208
 
 
209
/*!
 
210
    \fn void QVarLengthArray::append(const T &t)
 
211
 
 
212
    Appends item \a t to the array, extending the array if necessary.
 
213
 
 
214
    \sa removeLast()
 
215
*/
 
216
 
 
217
 
 
218
/*!
 
219
    \fn inline void QVarLengthArray::removeLast()
 
220
    \since 4.5
 
221
 
 
222
    Decreases the size of the array by one.  The allocated size is not changed.
 
223
 
 
224
    \sa append()
 
225
*/
 
226
 
 
227
/*!
 
228
    \fn void QVarLengthArray::append(const T *buf, int size)
 
229
 
 
230
    Appends \a size amount of items referenced by \a buf to this array.
 
231
*/
 
232
 
 
233
 
 
234
/*! \fn T *QVarLengthArray::data()
 
235
 
 
236
    Returns a pointer to the data stored in the array. The pointer can
 
237
    be used to access and modify the items in the array.
 
238
 
 
239
    Example:
 
240
    \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3
 
241
 
 
242
    The pointer remains valid as long as the array isn't reallocated.
 
243
 
 
244
    This function is mostly useful to pass an array to a function
 
245
    that accepts a plain C++ array.
 
246
 
 
247
    \sa constData(), operator[]()
 
248
*/
 
249
 
 
250
/*! \fn const T *QVarLengthArray::data() const
 
251
 
 
252
    \overload
 
253
*/
 
254
 
 
255
/*! \fn const T *QVarLengthArray::constData() const
 
256
 
 
257
    Returns a const pointer to the data stored in the array. The
 
258
    pointer can be used to access the items in the array. The
 
259
    pointer remains valid as long as the array isn't reallocated.
 
260
 
 
261
    This function is mostly useful to pass an array to a function
 
262
    that accepts a plain C++ array.
 
263
 
 
264
    \sa data(), operator[]()
 
265
*/
 
266
 
 
267
/*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other)
 
268
    Assigns \a other to this array and returns a reference to this array.
 
269
 */
 
270
 
 
271
/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)
 
272
    Constructs a copy of \a other.
 
273
 */
 
274