1QValueVector(3qt) QValueVector(3qt)
2
6 QValueVector - Value-based template class that provides a dynamic array
7
9 All the functions in this class are reentrant when Qt is built with
10 thread support.</p>
11 #include <qvaluevector.h>
13 Public Members
15 typedef T value_type
16 typedef value_type * pointer
17 typedef const value_type * const_pointer
18 typedef value_type * iterator
19 typedef const value_type * const_iterator
20 typedef value_type & reference
21 typedef const value_type & const_reference
22 typedef size_t size_type
23 typedef ptrdiff_t difference_type
24 QValueVector ()
25 QValueVector ( const QValueVector<T> & v )
26 QValueVector ( size_type n, const T & val = T ( ) )
27 QValueVector ( std::vector<T> & v )
28 QValueVector ( const std::vector<T> & v )
29 ~QValueVector ()
30 QValueVector<T> & operator= ( const QValueVector<T> & v )
31 QValueVector<T> & operator= ( const std::vector<T> & v )
32 size_type size () const
33 bool empty () const
34 size_type capacity () const
35 iterator begin ()
36 const_iterator begin () const
37 const_iterator constBegin () const
38 iterator end ()
39 const_iterator end () const
40 const_iterator constEnd () const
41 reference at ( size_type i, bool * ok = 0 )
42 const_reference at ( size_type i, bool * ok = 0 ) const
43 reference operator[] ( size_type i )
44 const_reference operator[] ( size_type i ) const
45 reference front ()
46 const_reference front () const
47 reference back ()
48 const_reference back () const
49 void push_back ( const T & x )
50 void pop_back ()
51 iterator insert ( iterator pos, const T & x )
52 iterator insert ( iterator pos, size_type n, const T & x )
53 void reserve ( size_type n )
54 void resize ( size_type n, const T & val = T ( ) )
55 void clear ()
56 iterator erase ( iterator pos )
57 iterator erase ( iterator first, iterator last )
58 bool operator== ( const QValueVector<T> & x )
59 bool operator== ( const QValueVector<T> & x ) const
60 typedef T ValueType
61 typedef ValueType * Iterator
62 typedef const ValueType * ConstIterator
63 size_type count () const
64 bool isEmpty () const
65 reference first ()
66 const_reference first () const
67 reference last ()
68 const_reference last () const
69 void append ( const T & x )
70
72 The QValueVector class is a value-based template class that provides a
73 dynamic array.
74 QValueVector is a Qt implementation of an STL-like vector container. It
76 can be used in your application if the standard vector is not available
77 for your target platforms. QValueVector is part of the Qt Template
78 Library.
79 QValueVector<T> defines a template instance to create a vector of
81 values that all have the class T. QValueVector does not store pointers
82 to the members of the vector; it holds a copy of every member.
83 QValueVector is said to be value based; in contrast, QPtrList and QDict
84 are pointer based.
85 QValueVector contains and manages a collection of objects of type T and
87 provides random access iterators that allow the contained objects to be
88 addressed. QValueVector owns the contained elements. For more relaxed
89 ownership semantics, see QPtrCollection and friends, which are pointer-
90 based containers.
91 QValueVector provides good performance if you append or remove elements
93 from the end of the vector. If you insert or remove elements from
94 anywhere but the end, performance is very bad. The reason for this is
95 that elements must to be copied into new positions.
96 Some classes cannot be used within a QValueVector: for example, all
98 classes derived from QObject and thus all classes that implement
99 widgets. Only values can be used in a QValueVector. To qualify as a
100 value the class must provide:
101 a copy constructor;
103 an assignment operator;
105 a default constructor, i.e., a constructor that does not take any
107 arguments.
108 Note that C++ defaults to field-by-field assignment operators and copy
110 constructors if no explicit version is supplied. In many cases this is
111 sufficient.
112 QValueVector uses an STL-like syntax to manipulate and address the
114 objects it contains. See this document for more information.
115 Example:
117 #include <qvaluevector.h>
119 #include <qstring.h>
120 #include <stdio.h>
121 class Employee
122 {
123 public:
124 Employee(): s(0) {}
125 Employee( const QString& name, int salary )
126 : n( name ), s( salary )
127 { }
128 QString name() const { return n; }
129 int salary() const { return s; }
130 void setSalary( int salary ) { s = salary; }
131 private:
132 QString n;
133 int s;
134 };
135 int main()
136 {
137 typedef QValueVector<Employee> EmployeeVector;
138 EmployeeVector vec( 3 ); // vector of 3 Employees
139 vec[0] = Employee( "Bill", 50000 );
140 vec[1] = Employee( "Steve", 80000 );
141 vec[2] = Employee( "Ron", 60000 );
142 Employee joe( "Joe", 50000 );
143 vec.push_back( joe ); // vector expands to accommodate 4 Employees
144 joe.setSalary( 70000 );
145 EmployeeVector::iterator it;
146 for( it = vec.begin(); it != vec.end(); ++it )
147 printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() );
148 return 0;
149 }
150 Program output:
152 Bill earns 50000
154 Steve earns 80000
155 Ron earns 60000
156 Joe earns 50000
157 As you can see, the most recent change to Joe's salary did not affect
159 the value in the vector because the vector created a copy of Joe's
160 entry.
161 Many Qt functions return const value vectors; to iterate over these you
163 should make a copy and iterate over the copy.
164 There are several ways to find items in the vector. The begin() and
166 end() functions return iterators to the beginning and end of the
167 vector. The advantage of getting an iterator is that you can move
168 forward or backward from this position by incrementing/decrementing the
169 iterator. The iterator returned by end() points to the element which is
170 one past the last element in the container. The past-the-end iterator
171 is still associated with the vector it belongs to, however it is not
172 dereferenceable; operator*() will not return a well-defined value. If
173 the vector is empty(), the iterator returned by begin() will equal the
174 iterator returned by end().
175 The fastest way to access an element of a vector is by using
177 operator[]. This function provides random access and will return a
178 reference to the element located at the specified index. Thus, you can
179 access every element directly, in constant time, providing you know the
180 location of the element. It is undefined to access an element that does
181 not exist (your application will probably crash). For example:
182 QValueVector<int> vec1; // an empty vector
184 vec1[10] = 4; // WARNING: undefined, probably a crash
185 QValueVector<QString> vec2(25); // initialize with 25 elements
186 vec2[10] = "Dave"; // OK
187 Whenever inserting, removing or referencing elements in a vector,
189 always make sure you are referring to valid positions. For example:
190 void func( QValueVector<int>& vec )
192 {
193 if ( vec.size() > 10 ) {
194 vec[9] = 99; // OK
195 }
196 };
197 The iterators provided by vector are random access iterators, therefore
199 you can use them with many generic algorithms, for example, algorithms
200 provided by the STL or the QTL.
201 Another way to find an element in the vector is by using the
203 std::find() or qFind() algorithms. For example:
204 QValueVector<int> vec;
206 ...
207 QValueVector<int>::const_iterator it = qFind( vec.begin(), vec.end(), 3 );
208 if ( it != vector.end() )
209 // 'it' points to the found element
210 It is safe to have multiple iterators on the vector at the same time.
212 Since QValueVector manages memory dynamically, all iterators can become
213 invalid if a memory reallocation occurs. For example, if some member of
214 the vector is removed, iterators that point to the removed element and
215 to all following elements become invalidated. Inserting into the middle
216 of the vector will invalidate all iterators. For convenience, the
217 function back() returns a reference to the last element in the vector,
218 and front() returns a reference to the first element. If the vector is
219 empty(), both back() and front() have undefined behavior (your
220 application will crash or do unpredictable things). Use back() and
221 front() with caution, for example:
222 QValueVector<int> vec( 3 );
224 vec.push_back( 1 );
225 vec.push_back( 2 );
226 vec.push_back( 3 );
227 ...
228 if ( !vec.empty() ) {
229 // OK: modify the first element
230 int& i = vec.front();
231 i = 18;
232 }
233 ...
234 QValueVector<double> dvec;
235 double d = dvec.back(); // undefined behavior
236 Because QValueVector manages memory dynamically, it is recommended that
238 you contruct a vector with an initial size. Inserting and removing
239 elements happens fastest when:
240 Inserting or removing elements happens at the end() of the vector;
242 The vector does not need to allocate additional memory.
244 By creating a QValueVector with a sufficiently large initial size,
246 there will be less memory allocations. Do not use an initial size that
247 is too big, since it will still take time to construct all the empty
248 entries, and the extra space will be wasted if it is never used.
249 Because QValueVector is value-based there is no need to be careful
251 about deleting elements in the vector. The vector holds its own copies
252 and will free them if the corresponding member or the vector itself is
253 deleted. You can force the vector to free all of its items with
254 clear().
255 QValueVector is shared implicitly, which means it can be copied in
257 constant time. If multiple QValueVector instances share the same data
258 and one needs to modify its contents, this modifying instance makes a
259 copy and modifies its private copy; it thus does not affect the other
260 instances. This is often called "copy on write". If a QValueVector is
261 being used in a multi-threaded program, you must protect all access to
262 the vector. See QMutex.
263 There are several ways to insert elements into the vector. The
265 push_back() function insert elements into the end of the vector, and is
266 usually fastest. The insert() function can be used to add elements at
267 specific positions within the vector.
268 Items can be also be removed from the vector in several ways. There are
270 several variants of the erase() function which removes a specific
271 element, or range of elements, from the vector.
272 Vectors can be also sorted with various STL algorithms , or it can be
274 sorted using the Qt Template Library. For example with qHeapSort():
275 Example:
277 QValueVector<int> v( 4 );
279 v.push_back( 5 );
280 v.push_back( 8 );
281 v.push_back( 3 );
282 v.push_back( 4 );
283 qHeapSort( v );
284 QValueVector stores its elements in contiguous memory. This means that
286 you can use a QValueVector in any situation that requires an array.
287 See also Qt Template Library Classes, Implicitly and Explicitly Shared
289 Classes, and Non-GUI Classes.
290 Member Type Documentation
293 The vector's const iterator type.
294
296 The vector's iterator type.
297
299 The type of the object stored in the vector.
300
302 The vector's const iterator type.
303
305 The const pointer to T type.
306
308 The const reference to T type.
309
311 A signed integral type used to represent the distance between two
312 iterators.
313
315 The vector's iterator type.
316
318 The pointer to T type.
319
321 The reference to T type.
322
324 An unsigned integral type, used to represent various sizes.
325
327 The type of the object stored in the vector.
328
331 Constructs an empty vector without any elements. To create a vector
332 which reserves an initial amount of space for elements, use
333 QValueVector(size_type n).
334
336 Constructs a copy of v.
337 This operation costs O(1) time because QValueVector is implicitly
339 shared.
340 The first modification to the vector does takes O(n) time, because the
342 elements must be copied.
343
345 Constructs a vector with an initial size of n elements. Each element is
346 initialized with the value of val.
347
349 Constructs a copy of v.
350
352 This operation costs O(n) time because v is copied.
353
355 Destroys the vector, destroying all elements and freeing the allocated
356 memory. References to the values in the vector and all iterators of
357 this vector become invalidated. Note that it is impossible for an
358 iterator to check whether or not it is valid: QValueVector is tuned for
359 performance, not for error checking.
360
362 Appends a copy of x to the end of the vector.
363 See also push_back() and insert().
365
367 Returns a reference to the element with index i. If ok is non-null, and
368 the index i is out of range, *ok is set to FALSE and the returned
369 reference is undefined. If the index i is within the range of the
370 vector, and ok is non-null, *ok is set to TRUE and the returned
371 reference is well defined.
372
374 This is an overloaded member function, provided for convenience. It
375 behaves essentially like the above function.
376 Returns a const reference to the element with index i. If ok is non-
378 null, and the index i is out of range, *ok is set to FALSE and the
379 returned reference is undefined. If the index i is within the range of
380 the vector, and ok is non-null, *ok is set to TRUE and the returned
381 reference is well defined.
382
384 Returns a reference to the last element in the vector. If there is no
385 last element, this function has undefined behavior.
386 See also empty() and front().
388
390 This is an overloaded member function, provided for convenience. It
391 behaves essentially like the above function.
392 Returns a const reference to the last element in the vector. If there
394 is no last element, this function has undefined behavior.
395 See also empty() and front().
397
399 Returns an iterator pointing to the beginning of the vector. If the
400 vector is empty(), the returned iterator will equal end().
401
403 This is an overloaded member function, provided for convenience. It
404 behaves essentially like the above function.
405 Returns a const iterator pointing to the beginning of the vector. If
407 the vector is empty(), the returned iterator will equal end().
408
410 Returns the maximum number of elements that can be stored in the vector
411 without forcing memory reallocation. If memory reallocation takes
412 place, some or all iterators may become invalidated.
413
415 Removes all the elements from the vector.
416
418 Returns a const iterator pointing to the beginning of the vector. If
419 the vector is empty(), the returned iterator will equal end().
420 See also constEnd().
422
424 Returns a const iterator pointing behind the last element of the
425 vector.
426 See also constBegin().
428
430 Returns the number of items in the vector.
431 See also isEmpty().
433
435 Returns TRUE if the vector is empty; otherwise returns FALSE.
436 Equivalent to size()==0, only faster.
437 This function is provided for STL compatibility. It is equivalent to
439 isEmpty().
440 See also size().
442
444 Returns an iterator pointing behind the last element of the vector.
445
447 This is an overloaded member function, provided for convenience. It
448 behaves essentially like the above function.
449 Returns a const iterator pointing behind the last element of the
451 vector.
452
454 Removes the element at position pos and returns the position of the
455 next element.
456
458 This is an overloaded member function, provided for convenience. It
459 behaves essentially like the above function.
460 Removes all elements from first up to but not including last and
462 returns the position of the next element.
463
465 Returns a reference to the first item in the vector. If there is no
466 first item, this function has undefined behavior.
467 See also empty() and last().
469
471 This is an overloaded member function, provided for convenience. It
472 behaves essentially like the above function.
473
475 Returns a reference to the first element in the vector. If there is no
476 first element, this function has undefined behavior.
477 See also empty() and back().
479
481 This is an overloaded member function, provided for convenience. It
482 behaves essentially like the above function.
483 Returns a const reference to the first element in the vector. If there
485 is no first element, this function has undefined behavior.
486 See also empty() and back().
488
490 Inserts a copy of x at the position immediately before pos.
491 See also push_back().
493
495 This is an overloaded member function, provided for convenience. It
496 behaves essentially like the above function.
497 Inserts n copies of x immediately before position x.
499 See also push_back().
501
503 Returns TRUE if the vector is empty; returns FALSE otherwise.
504 See also count().
506
508 Returns a reference to the last item in the vector. If there is no last
509 item, this function has undefined behavior.
510 See also empty() and first().
512
514 This is an overloaded member function, provided for convenience. It
515 behaves essentially like the above function.
516
518 Assigns v to this vector and returns a reference to this vector.
519 All iterators of the current vector become invalidated by this
521 operation. The cost of such an assignment is O(1) since QValueVector is
522 implicitly shared.
523
525 This is an overloaded member function, provided for convenience. It
526 behaves essentially like the above function.
527 Assigns v to this vector and returns a reference to this vector.
529 All iterators of the current vector become invalidated by this
531 operation. The cost of this assignment is O(n) since v is copied.
532
534 Returns TRUE if each element in this vector equals each corresponding
535 element in x; otherwise returns FALSE.
536
538 This is an overloaded member function, provided for convenience. It
539 behaves essentially like the above function.
540 Returns TRUE if each element in this vector equals each corresponding
542 element in x; otherwise returns FALSE.
543
545 Returns a reference to the element at index i. If i is out of range,
546 this function has undefined behavior.
547 See also at().
549
551 This is an overloaded member function, provided for convenience. It
552 behaves essentially like the above function.
553 Returns a const reference to the element at index i. If i is out of
555 range, this function has undefined behavior.
556 See also at().
558
560 Removes the last item from the vector.
561 This function is provided for STL compatibility.
563
565 Appends a copy of x to the end of the vector. This is the fastest way
566 to add new elements.
567 This function is provided for STL compatibility. It is equivalent to
569 append().
570 See also insert().
572
574 Increases the vector's capacity. If n is less than or equal to
575 capacity(), nothing happens. Otherwise, additional memory is allocated
576 so that capacity() will be increased to a value greater than or equal
577 to n. All iterators will then become invalidated. Note that the
578 vector's size() and the values of existing elements remain unchanged.
579
581 Changes the size of the vector to n. If n is greater than the current
582 size(), elements are added to the end and initialized with the value of
583 val. If n is less than size(), elements are removed from the end. If n
584 is equal to size() nothing happens.
585
587 Returns the number of elements in the vector.
588 This function is provided for STL compatibility. It is equivalent to
590 count().
591 See also empty().
593
596 http://doc.trolltech.com/qvaluevector.html
597 http://www.trolltech.com/faq/tech.html
598
600 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
601 license file included in the distribution for a complete license
602 statement.
603
605 Generated automatically from the source code.
606
608 If you find a bug in Qt, please report it as described in
609 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
610 help you. Thank you.
611 The definitive Qt documentation is provided in HTML format; it is
613 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
614 web browser. This man page is provided as a convenience for those users
615 who prefer man pages, although this format is not officially supported
616 by Trolltech.
617 If you find errors in this manual page, please report them to qt-
619 bugs@trolltech.com. Please include the name of the manual page
620 (qvaluevector.3qt) and the Qt version (3.3.8).
621Trolltech AS 2 February 2007 QValueVector(3qt)