← Back to branch summary

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

« back to all changes in this revision

Viewing changes to src/qt3support/tools/q3memarray.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/qt3support/tools/q3memarray.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 Q3MemArray
 
44
    \brief The Q3MemArray class is a template class that provides arrays of simple types.
 
45
    \compat
 
46
 
 
47
    Q3MemArray is implemented as a template class. Define a template
 
48
    instance Q3MemArray\<X\> to create an array that contains X items.
 
49
 
 
50
    Q3MemArray stores the array elements directly in the array. It can
 
51
    only deal with simple types (i.e. C++ types, structs, and classes
 
52
    that have no constructors, destructors, or virtual functions).
 
53
    Q3MemArray uses bitwise operations to copy and compare array
 
54
    elements. 
 
55
 
 
56
    The Q3PtrVector collection class is also a kind of array. Like most
 
57
    old Qt collection classes, it uses pointers to the contained items.
 
58
 
 
59
    Q3MemArray uses explicit sharing with a
 
60
    reference count. If more than one array shares common data and one
 
61
    of the arrays is modified, all the arrays are modified.
 
62
 
 
63
    The benefit of sharing is that a program does not need to duplicate
 
64
    data when it is not required, which results in lower memory use
 
65
    and less copying of data.
 
66
 
 
67
    Example:
 
68
    \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0
 
69
 
 
70
    Program output:
 
71
    \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1
 
72
 
 
73
    Note concerning the use of Q3MemArray for manipulating structs or
 
74
    classes: Compilers will often pad the size of structs of odd sizes
 
75
    up to the nearest word boundary. This will then be the size
 
76
    Q3MemArray will use for its bitwise element comparisons. Because
 
77
    the remaining bytes will typically be uninitialized, this can
 
78
    cause find() etc. to fail to find the element. Example:
 
79
 
 
80
    \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2
 
81
 
 
82
    To work around this, make sure that you use a struct where
 
83
    sizeof() returns the same as the sum of the sizes of the members
 
84
    either by changing the types of the struct members or by adding
 
85
    dummy members.
 
86
 
 
87
    Q3MemArray data can be traversed by iterators (see begin() and
 
88
    end()). The number of items is returned by count(). The array can
 
89
    be resized with resize() and filled using fill().
 
90
 
 
91
    You can make a shallow copy of the array with assign() (or
 
92
    operator=()) and a deep copy with duplicate().
 
93
 
 
94
    Search for values in the array with find() and contains(). For
 
95
    sorted arrays (see sort()) you can search using bsearch().
 
96
 
 
97
    You can set the data directly using setRawData() and
 
98
    resetRawData(), although this requires care.
 
99
*/
 
100
 
 
101
/*! \fn Q3MemArray::operator QVector<type>() const
 
102
 
 
103
    Automatically converts the Q3MemArray<type> into a QVector<type>.
 
104
*/
 
105
 
 
106
/*! \typedef Q3MemArray::Iterator
 
107
    A Q3MemArray iterator.
 
108
    \sa begin() end()
 
109
*/
 
110
/*! \typedef Q3MemArray::ConstIterator
 
111
    A const Q3MemArray iterator.
 
112
    \sa begin() end()
 
113
*/
 
114
/*! \typedef Q3MemArray::ValueType
 
115
    \internal
 
116
*/
 
117
 
 
118
/*!
 
119
    \fn Q3MemArray::Q3MemArray()
 
120
 
 
121
    Constructs a null array.
 
122
 
 
123
    \sa isNull()
 
124
*/
 
125
 
 
126
/*!
 
127
    \fn Q3MemArray::Q3MemArray( int size )
 
128
 
 
129
    Constructs an array with room for \a size elements. Makes a null
 
130
    array if \a size == 0.
 
131
 
 
132
    The elements are left uninitialized.
 
133
 
 
134
    \sa resize(), isNull()
 
135
*/
 
136
 
 
137
/*!
 
138
    \fn Q3MemArray::Q3MemArray( const Q3MemArray<type> &a )
 
139
 
 
140
    Constructs a shallow copy of \a a.
 
141
 
 
142
    \sa assign()
 
143
*/
 
144
 
 
145
/*!
 
146
    \fn Q3MemArray::Q3MemArray(const QVector<type> &vector)
 
147
 
 
148
    Constructs a copy of \a vector.
 
149
*/
 
150
 
 
151
/*!
 
152
    \fn Q3MemArray::Q3MemArray(int arg1, int arg2)
 
153
 
 
154
    Constructs an array \e{without allocating} array space. The
 
155
    arguments \a arg1 and \a arg2 should be zero. Use at your own
 
156
    risk.
 
157
*/
 
158
 
 
159
/*!
 
160
    \fn Q3MemArray::~Q3MemArray()
 
161
 
 
162
    Dereferences the array data and deletes it if this was the last
 
163
    reference.
 
164
*/
 
165
 
 
166
/*!
 
167
    \fn Q3MemArray<type> &Q3MemArray::operator=( const Q3MemArray<type> &a )
 
168
 
 
169
    Assigns a shallow copy of \a a to this array and returns a
 
170
    reference to this array.
 
171
 
 
172
    Equivalent to assign( a ).
 
173
*/
 
174
 
 
175
/*!
 
176
    \fn type *Q3MemArray::data() const
 
177
 
 
178
    Returns a pointer to the actual array data.
 
179
 
 
180
    The array is a null array if data() == 0 (null pointer).
 
181
 
 
182
    \sa isNull()
 
183
*/
 
184
 
 
185
/*!
 
186
    \fn uint Q3MemArray::nrefs() const
 
187
 
 
188
    Returns the reference count for the shared array data. This
 
189
    reference count is always greater than zero.
 
190
*/
 
191
 
 
192
/*!
 
193
    \fn uint Q3MemArray::size() const
 
194
 
 
195
    Returns the size of the array (maximum number of elements).
 
196
 
 
197
    The array is a null array if size() == 0.
 
198
 
 
199
    \sa isNull(), resize()
 
200
*/
 
201
 
 
202
/*!
 
203
    \fn uint Q3MemArray::count() const
 
204
 
 
205
    Returns the same as size().
 
206
 
 
207
    \sa size()
 
208
*/
 
209
 
 
210
/*!
 
211
    \fn bool Q3MemArray::isEmpty() const
 
212
 
 
213
    Returns TRUE if the array is empty; otherwise returns FALSE.
 
214
 
 
215
    isEmpty() is equivalent to isNull() for Q3MemArray (unlike
 
216
    QString).
 
217
*/
 
218
 
 
219
/*!
 
220
    \fn bool Q3MemArray::isNull() const
 
221
 
 
222
    Returns TRUE if the array is null; otherwise returns FALSE.
 
223
 
 
224
    A null array has size() == 0 and data() == 0.
 
225
*/
 
226
 
 
227
/*!
 
228
    \fn bool Q3MemArray::resize( uint size, Optimization optim )
 
229
 
 
230
    Resizes (expands or shrinks) the array to \a size elements. The
 
231
    array becomes a null array if \a size == 0.
 
232
 
 
233
    Returns TRUE if successful, or FALSE if the memory cannot be
 
234
    allocated.
 
235
 
 
236
    New elements are not initialized.
 
237
 
 
238
    \a optim is either Q3GArray::MemOptim (the default) or
 
239
    Q3GArray::SpeedOptim. When optimizing for speed rather than memory
 
240
    consumption, the array uses a smart grow and shrink algorithm that
 
241
    might allocate more memory than is actually needed for \a size
 
242
    elements. This speeds up subsequent resize operations, for example
 
243
    when appending many elements to an array, since the space has
 
244
    already been allocated.
 
245
 
 
246
    \sa size()
 
247
*/
 
248
 
 
249
/*!
 
250
    \fn bool Q3MemArray::resize( uint size )
 
251
 
 
252
    \overload
 
253
 
 
254
    Resizes (expands or shrinks) the array to \a size elements. The
 
255
    array becomes a null array if \a size == 0.
 
256
 
 
257
    Returns TRUE if successful, i.e. if the memory can be allocated;
 
258
    otherwise returns FALSE.
 
259
 
 
260
    New elements are not initialized.
 
261
 
 
262
    \sa size()
 
263
*/
 
264
 
 
265
/*!
 
266
    \fn bool Q3MemArray::truncate( uint pos )
 
267
 
 
268
    Truncates the array at position \a pos.
 
269
 
 
270
    Returns TRUE if successful, i.e. if the memory can be allocated;
 
271
    otherwise returns FALSE.
 
272
 
 
273
    Equivalent to resize(\a pos).
 
274
 
 
275
    \sa resize()
 
276
*/
 
277
 
 
278
/*!
 
279
    \fn bool Q3MemArray::fill( const type &v, int size )
 
280
 
 
281
    Fills the array with the value \a v. If \a size is specified as
 
282
    different from -1, then the array will be resized before being
 
283
    filled.
 
284
 
 
285
    Returns TRUE if successful, i.e. if \a size is -1, or \a size is
 
286
    != -1 and the memory can be allocated; otherwise returns FALSE.
 
287
 
 
288
    \sa resize()
 
289
*/
 
290
 
 
291
/*!
 
292
    \fn void Q3MemArray::detach()
 
293
 
 
294
    Detaches this array from shared array data; i.e. it makes a
 
295
    private, deep copy of the data.
 
296
 
 
297
    Copying will be performed only if the \link nrefs() reference
 
298
    count\endlink is greater than one.
 
299
 
 
300
    \sa copy()
 
301
*/
 
302
 
 
303
/*!
 
304
    \fn Q3MemArray<type> Q3MemArray::copy() const
 
305
 
 
306
    Returns a deep copy of this array.
 
307
 
 
308
    \sa detach(), duplicate()
 
309
*/
 
310
 
 
311
/*!
 
312
    \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<type> &a )
 
313
 
 
314
    Shallow copy. Dereferences the current array and references the
 
315
    data contained in \a a instead. Returns a reference to this array.
 
316
 
 
317
    \sa operator=()
 
318
*/
 
319
 
 
320
/*!
 
321
    \fn Q3MemArray<type> &Q3MemArray::assign( const type *data, uint size )
 
322
 
 
323
    \overload
 
324
 
 
325
    Shallow copy. Dereferences the current array and references the
 
326
    array data \a data, which contains \a size elements. Returns a
 
327
    reference to this array.
 
328
 
 
329
    Do not delete \a data later; Q3MemArray will call free() on it
 
330
    at the right time.
 
331
*/
 
332
 
 
333
/*!
 
334
    \fn Q3MemArray<type> &Q3MemArray::duplicate( const Q3MemArray<type> &a )
 
335
 
 
336
    Deep copy. Dereferences the current array and obtains a copy of
 
337
    the data contained in \a a instead. Returns a reference to this
 
338
    array.
 
339
 
 
340
    \sa copy()
 
341
*/
 
342
 
 
343
/*!
 
344
    \fn Q3MemArray<type> &Q3MemArray::duplicate( const type *data, uint size )
 
345
 
 
346
    \overload
 
347
 
 
348
    Deep copy. Dereferences the current array and obtains a copy of
 
349
    the array data \a data instead. Returns a reference to this array.
 
350
    The size of the array is given by \a size.
 
351
 
 
352
    \sa copy()
 
353
*/
 
354
 
 
355
/*!
 
356
    \fn Q3MemArray<type> &Q3MemArray::setRawData( const type *data, uint size )
 
357
 
 
358
    Sets raw data and returns a reference to the array.
 
359
 
 
360
    Dereferences the current array and sets the new array data to \a
 
361
    data and the new array size to \a size. Do not attempt to resize
 
362
    or re-assign the array data when raw data has been set. Call
 
363
    resetRawData(\a data, \a size) to reset the array.
 
364
 
 
365
    Setting raw data is useful because it sets Q3MemArray data without
 
366
    allocating memory or copying data.
 
367
 
 
368
    Example I (intended use):
 
369
    \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3
 
370
 
 
371
    Example II (you don't want to do this):
 
372
    \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4
 
373
 
 
374
    \warning If you do not call resetRawData(), Q3MemArray will attempt
 
375
    to deallocate or reallocate the raw data, which might not be too
 
376
    good. Be careful.
 
377
 
 
378
    \sa resetRawData()
 
379
*/
 
380
 
 
381
/*!
 
382
    \fn void Q3MemArray::resetRawData( const type *data, uint size )
 
383
 
 
384
    Removes internal references to the raw data that was set using
 
385
    setRawData(). This means that Q3MemArray no longer has access to
 
386
    the \a data, so you are free to manipulate \a data as you wish.
 
387
    You can now use the Q3MemArray without affecting the original \a
 
388
    data, for example by calling setRawData() with a pointer to some
 
389
    other data.
 
390
 
 
391
    The arguments must be the \a data and length, \a size, that were
 
392
    passed to setRawData(). This is for consistency checking.
 
393
 
 
394
    \sa setRawData()
 
395
*/
 
396
 
 
397
/*!
 
398
    \fn int Q3MemArray::find( const type &v, uint index ) const
 
399
 
 
400
    Finds the first occurrence of \a v, starting at position \a index.
 
401
 
 
402
    Returns the position of \a v, or -1 if \a v could not be found.
 
403
 
 
404
    \sa contains()
 
405
*/
 
406
 
 
407
/*!
 
408
    \fn int Q3MemArray::contains( const type &v ) const
 
409
 
 
410
    Returns the number of times \a v occurs in the array.
 
411
 
 
412
    \sa find()
 
413
*/
 
414
 
 
415
/*!
 
416
    \fn void Q3MemArray::sort()
 
417
 
 
418
    Sorts the array elements in ascending order, using bitwise
 
419
    comparison (memcmp()).
 
420
 
 
421
    \sa bsearch()
 
422
*/
 
423
 
 
424
/*!
 
425
    \fn int Q3MemArray::bsearch( const type &v ) const
 
426
 
 
427
    In a sorted array (as sorted by sort()), finds the first
 
428
    occurrence of \a v by using a binary search. For a sorted
 
429
    array this is generally much faster than find(), which does
 
430
    a linear search.
 
431
 
 
432
    Returns the position of \a v, or -1 if \a v could not be found.
 
433
 
 
434
    \sa sort(), find()
 
435
*/
 
436
 
 
437
/*!
 
438
    \fn type &Q3MemArray::operator[]( int index ) const
 
439
 
 
440
    Returns a reference to the element at position \a index in the
 
441
    array.
 
442
 
 
443
    This can be used to both read and set an element. Equivalent to
 
444
    at().
 
445
 
 
446
    \sa at()
 
447
*/
 
448
 
 
449
/*!
 
450
    \fn type &Q3MemArray::at( uint index ) const
 
451
 
 
452
    Returns a reference to the element at position \a index in the array.
 
453
 
 
454
    This can be used to both read and set an element.
 
455
 
 
456
    \sa operator[]()
 
457
*/
 
458
 
 
459
/*!
 
460
    \fn Q3MemArray::operator const type *() const
 
461
 
 
462
    Cast operator. Returns a pointer to the array.
 
463
 
 
464
    \sa data()
 
465
*/
 
466
 
 
467
/*!
 
468
    \fn bool Q3MemArray::operator==( const Q3MemArray<type> &a ) const
 
469
 
 
470
    Returns TRUE if this array is equal to \a a; otherwise returns
 
471
    FALSE.
 
472
 
 
473
    The two arrays are compared bitwise.
 
474
 
 
475
    \sa operator!=()
 
476
*/
 
477
 
 
478
/*!
 
479
    \fn bool Q3MemArray::operator!=( const Q3MemArray<type> &a ) const
 
480
 
 
481
    Returns TRUE if this array is different from \a a; otherwise
 
482
    returns FALSE.
 
483
 
 
484
    The two arrays are compared bitwise.
 
485
 
 
486
    \sa operator==()
 
487
*/
 
488
 
 
489
/*!
 
490
    \fn Iterator Q3MemArray::begin()
 
491
 
 
492
    Returns an iterator pointing at the beginning of this array. This
 
493
    iterator can be used in the same way as the iterators of
 
494
    Q3ValueList and QMap, for example.
 
495
*/
 
496
 
 
497
/*!
 
498
    \fn Iterator Q3MemArray::end()
 
499
 
 
500
    Returns an iterator pointing behind the last element of this
 
501
    array. This iterator can be used in the same way as the iterators
 
502
    of Q3ValueList and QMap, for example.
 
503
*/
 
504
 
 
505
/*!
 
506
    \fn ConstIterator Q3MemArray::begin() const
 
507
 
 
508
    \overload
 
509
 
 
510
    Returns a const iterator pointing at the beginning of this array.
 
511
    This iterator can be used in the same way as the iterators of
 
512
    Q3ValueList and QMap, for example.
 
513
*/
 
514
 
 
515
/*!
 
516
    \fn ConstIterator Q3MemArray::end() const
 
517
 
 
518
    \overload
 
519
 
 
520
    Returns a const iterator pointing behind the last element of this
 
521
    array. This iterator can be used in the same way as the iterators
 
522
    of Q3ValueList and QMap, for example. 
 
523
*/