0
|
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 Q3ValueVector
|
|
44 |
\brief The Q3ValueVector class is a value-based template class that provides a dynamic array.
|
|
45 |
\compat
|
|
46 |
|
|
47 |
Q3ValueVector is a Qt implementation of an STL-like vector
|
|
48 |
container. It can be used in your application if the standard \c
|
|
49 |
vector is not available for your target platforms.
|
|
50 |
|
|
51 |
Q3ValueVector\<T\> defines a template instance to create a vector
|
|
52 |
of values that all have the class T. Q3ValueVector does not store
|
|
53 |
pointers to the members of the vector; it holds a copy of every
|
|
54 |
member. Q3ValueVector is said to be value based; in contrast,
|
|
55 |
Q3PtrList and Q3Dict are pointer based.
|
|
56 |
|
|
57 |
Q3ValueVector contains and manages a collection of objects of type
|
|
58 |
T and provides random access iterators that allow the contained
|
|
59 |
objects to be addressed. Q3ValueVector owns the contained
|
|
60 |
elements. For more relaxed ownership semantics, see Q3PtrCollection
|
|
61 |
and friends, which are pointer-based containers.
|
|
62 |
|
|
63 |
Q3ValueVector provides good performance if you append or remove
|
|
64 |
elements from the end of the vector. If you insert or remove
|
|
65 |
elements from anywhere but the end, performance is very bad. The
|
|
66 |
reason for this is that elements must to be copied into new
|
|
67 |
positions.
|
|
68 |
|
|
69 |
Some classes cannot be used within a Q3ValueVector: for example,
|
|
70 |
all classes derived from QObject and thus all classes that
|
|
71 |
implement widgets. Only values can be used in a Q3ValueVector. To
|
|
72 |
qualify as a value the class must provide:
|
|
73 |
\list
|
|
74 |
\i a copy constructor;
|
|
75 |
\i an assignment operator;
|
|
76 |
\i a default constructor, i.e., a constructor that does not take any arguments.
|
|
77 |
\endlist
|
|
78 |
|
|
79 |
Note that C++ defaults to field-by-field assignment operators and
|
|
80 |
copy constructors if no explicit version is supplied. In many
|
|
81 |
cases this is sufficient.
|
|
82 |
|
|
83 |
Q3ValueVector uses an STL-like syntax to manipulate and address the
|
|
84 |
objects it contains.
|
|
85 |
|
|
86 |
Example:
|
|
87 |
\snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0
|
|
88 |
|
|
89 |
Program output:
|
|
90 |
\snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1
|
|
91 |
|
|
92 |
As you can see, the most recent change to Joe's salary did not
|
|
93 |
affect the value in the vector because the vector created a copy
|
|
94 |
of Joe's entry.
|
|
95 |
|
|
96 |
Many Qt functions return const value vectors; to iterate over
|
|
97 |
these you should make a copy and iterate over the copy.
|
|
98 |
|
|
99 |
There are several ways to find items in the vector. The begin()
|
|
100 |
and end() functions return iterators to the beginning and end of
|
|
101 |
the vector. The advantage of getting an iterator is that you can
|
|
102 |
move forward or backward from this position by
|
|
103 |
incrementing/decrementing the iterator. The iterator returned by
|
|
104 |
end() points to the element which is one past the last element in
|
|
105 |
the container. The past-the-end iterator is still associated with
|
|
106 |
the vector it belongs to, however it is \e not dereferenceable;
|
|
107 |
operator*() will not return a well-defined value. If the vector is
|
|
108 |
empty(), the iterator returned by begin() will equal the iterator
|
|
109 |
returned by end().
|
|
110 |
|
|
111 |
The fastest way to access an element of a vector is by using
|
|
112 |
operator[]. This function provides random access and will return
|
|
113 |
a reference to the element located at the specified index. Thus,
|
|
114 |
you can access every element directly, in constant time, providing
|
|
115 |
you know the location of the element. It is undefined to access
|
|
116 |
an element that does not exist (your application will probably
|
|
117 |
crash). For example:
|
|
118 |
|
|
119 |
\snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2
|
|
120 |
|
|
121 |
Whenever inserting, removing or referencing elements in a vector,
|
|
122 |
always make sure you are referring to valid positions. For
|
|
123 |
example:
|
|
124 |
|
|
125 |
\snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3
|
|
126 |
|
|
127 |
The iterators provided by vector are random access iterators,
|
|
128 |
therefore you can use them with many generic algorithms, for
|
|
129 |
example, algorithms provided by the STL.
|
|
130 |
|
|
131 |
It is safe to have multiple iterators on the vector at the same
|
|
132 |
time. Since Q3ValueVector manages memory dynamically, all iterators
|
|
133 |
can become invalid if a memory reallocation occurs. For example,
|
|
134 |
if some member of the vector is removed, iterators that point to
|
|
135 |
the removed element and to all following elements become
|
|
136 |
invalidated. Inserting into the middle of the vector will
|
|
137 |
invalidate all iterators. For convenience, the function back()
|
|
138 |
returns a reference to the last element in the vector, and front()
|
|
139 |
returns a reference to the first element. If the vector is
|
|
140 |
empty(), both back() and front() have undefined behavior (your
|
|
141 |
application will crash or do unpredictable things). Use back() and
|
|
142 |
front() with caution, for example:
|
|
143 |
|
|
144 |
\snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4
|
|
145 |
|
|
146 |
Because Q3ValueVector manages memory dynamically, it is recommended
|
|
147 |
that you contruct a vector with an initial size. Inserting and
|
|
148 |
removing elements happens fastest when:
|
|
149 |
\list
|
|
150 |
\i Inserting or removing elements happens at the end() of the
|
|
151 |
vector;
|
|
152 |
\i The vector does not need to allocate additional memory.
|
|
153 |
\endlist
|
|
154 |
|
|
155 |
By creating a Q3ValueVector with a sufficiently large initial size,
|
|
156 |
there will be less memory allocations. Do not use an initial size
|
|
157 |
that is too big, since it will still take time to construct all
|
|
158 |
the empty entries, and the extra space will be wasted if it is
|
|
159 |
never used.
|
|
160 |
|
|
161 |
Because Q3ValueVector is value-based there is no need to be careful
|
|
162 |
about deleting elements in the vector. The vector holds its own
|
|
163 |
copies and will free them if the corresponding member or the
|
|
164 |
vector itself is deleted. You can force the vector to free all of
|
|
165 |
its items with clear().
|
|
166 |
|
|
167 |
Q3ValueVector is shared implicitly, which means it can be copied in
|
|
168 |
constant time. If multiple Q3ValueVector instances share the same
|
|
169 |
data and one needs to modify its contents, this modifying instance
|
|
170 |
makes a copy and modifies its private copy; it thus does not
|
|
171 |
affect the other instances. This is often called "copy on write".
|
|
172 |
If a Q3ValueVector is being used in a multi-threaded program, you
|
|
173 |
must protect all access to the vector. See QMutex.
|
|
174 |
|
|
175 |
There are several ways to insert elements into the vector. The
|
|
176 |
push_back() function insert elements into the end of the vector,
|
|
177 |
and is usually fastest. The insert() function can be used to add
|
|
178 |
elements at specific positions within the vector.
|
|
179 |
|
|
180 |
Items can be also be removed from the vector in several ways.
|
|
181 |
There are several variants of the erase() function which removes a
|
|
182 |
specific element, or range of elements, from the vector.
|
|
183 |
|
|
184 |
Q3ValueVector stores its elements in contiguous memory. This means
|
|
185 |
that you can use a Q3ValueVector in any situation that requires an
|
|
186 |
array.
|
|
187 |
*/
|
|
188 |
|
|
189 |
/*!
|
|
190 |
\fn Q3ValueVector::Q3ValueVector()
|
|
191 |
|
|
192 |
Constructs an empty vector without any elements. To create a
|
|
193 |
vector which reserves an initial amount of space for elements, use
|
|
194 |
\c Q3ValueVector(size_type n).
|
|
195 |
*/
|
|
196 |
|
|
197 |
/*!
|
|
198 |
\fn Q3ValueVector::Q3ValueVector( const Q3ValueVector<T>& v )
|
|
199 |
|
|
200 |
Constructs a copy of \a v.
|
|
201 |
|
|
202 |
This operation costs O(1) time because Q3ValueVector is implicitly
|
|
203 |
shared.
|
|
204 |
|
|
205 |
The first modification to the vector does takes O(n) time, because
|
|
206 |
the elements must be copied.
|
|
207 |
*/
|
|
208 |
|
|
209 |
/*!
|
|
210 |
\fn Q3ValueVector::Q3ValueVector( const std::vector<T>& v )
|
|
211 |
|
|
212 |
This operation costs O(n) time because \a v is copied.
|
|
213 |
*/
|
|
214 |
|
|
215 |
/*!
|
|
216 |
\fn Q3ValueVector::Q3ValueVector( QVector<T>::size_type n, const T& val )
|
|
217 |
|
|
218 |
Constructs a vector with an initial size of \a n elements. Each
|
|
219 |
element is initialized with the value of \a val.
|
|
220 |
*/
|
|
221 |
|
|
222 |
/*!
|
|
223 |
\fn Q3ValueVector<T>& Q3ValueVector::operator=( const Q3ValueVector<T>& v )
|
|
224 |
|
|
225 |
Assigns \a v to this vector and returns a reference to this vector.
|
|
226 |
|
|
227 |
All iterators of the current vector become invalidated by this
|
|
228 |
operation. The cost of such an assignment is O(1) since
|
|
229 |
Q3ValueVector is implicitly shared.
|
|
230 |
*/
|
|
231 |
|
|
232 |
/*!
|
|
233 |
\fn Q3ValueVector<T>& Q3ValueVector::operator=( const std::vector<T>& v )
|
|
234 |
|
|
235 |
\overload
|
|
236 |
|
|
237 |
Assigns \a v to this vector and returns a reference to this vector.
|
|
238 |
|
|
239 |
All iterators of the current vector become invalidated by this
|
|
240 |
operation. The cost of this assignment is O(n) since \a v is
|
|
241 |
copied.
|
|
242 |
*/
|
|
243 |
|
|
244 |
/*!
|
|
245 |
\fn T &Q3ValueVector::at( int i , bool* ok )
|
|
246 |
|
|
247 |
Returns a reference to the element with index \a i. If \a ok is
|
|
248 |
non-null, and the index \a i is out of range, *\a ok is set to
|
|
249 |
FALSE and the returned reference is undefined. If the index \a i
|
|
250 |
is within the range of the vector, and \a ok is non-null, *\a ok
|
|
251 |
is set to TRUE and the returned reference is well defined.
|
|
252 |
*/
|
|
253 |
|
|
254 |
/*!
|
|
255 |
\fn const T &Q3ValueVector::at( int i , bool* ok ) const
|
|
256 |
|
|
257 |
\overload
|
|
258 |
|
|
259 |
Returns a const reference to the element with index \a i. If \a ok
|
|
260 |
is non-null, and the index \a i is out of range, *\a ok is set to
|
|
261 |
FALSE and the returned reference is undefined. If the index \a i
|
|
262 |
is within the range of the vector, and \a ok is non-null, *\a ok
|
|
263 |
is set to TRUE and the returned reference is well defined.
|
|
264 |
*/
|
|
265 |
|
|
266 |
/*!
|
|
267 |
\fn void Q3ValueVector::resize( int n, const T& val = T() )
|
|
268 |
|
|
269 |
Changes the size of the vector to \a n. If \a n is greater than
|
|
270 |
the current size(), elements are added to the end and initialized
|
|
271 |
with the value of \a val. If \a n is less than size(), elements
|
|
272 |
are removed from the end. If \a n is equal to size() nothing
|
|
273 |
happens.
|
|
274 |
*/
|