source: trunk/src/qt3support/tools/q3memarray.qdoc@ 561

Last change on this file since 561 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: 14.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 \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.