source: trunk/doc/src/q3memarray.qdoc@ 348

Last change on this file since 348 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 14.1 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** 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 are unsure which license is appropriate for your use, please
37** contact the sales department 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.
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*/