1QValueVector(3qt)                                            QValueVector(3qt)
2
3
4

NAME

6       QValueVector - Value-based template class that provides a dynamic array
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qvaluevector.h>
13
14   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

DESCRIPTION

72       The QValueVector class is a value-based template class that provides a
73       dynamic array.
74
75       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
80       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
86       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
92       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
97       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
102       a copy constructor;
103
104       an assignment operator;
105
106       a default constructor, i.e., a constructor that does not take any
107       arguments.
108
109       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
113       QValueVector uses an STL-like syntax to manipulate and address the
114       objects it contains. See this document for more information.
115
116       Example:
117
118           #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
151       Program output:
152
153               Bill earns 50000
154               Steve earns 80000
155               Ron earns 60000
156               Joe earns 50000
157
158       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
162       Many Qt functions return const value vectors; to iterate over these you
163       should make a copy and iterate over the copy.
164
165       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
176       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
183           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
188       Whenever inserting, removing or referencing elements in a vector,
189       always make sure you are referring to valid positions. For example:
190
191           void func( QValueVector<int>& vec )
192           {
193               if ( vec.size() > 10 ) {
194                   vec[9] = 99; // OK
195               }
196           };
197
198       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
202       Another way to find an element in the vector is by using the
203       std::find() or qFind() algorithms. For example:
204
205           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
211       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
223           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
237       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
241       Inserting or removing elements happens at the end() of the vector;
242
243       The vector does not need to allocate additional memory.
244
245       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
250       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
256       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
264       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
269       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
273       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
276       Example:
277
278           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
285       QValueVector stores its elements in contiguous memory. This means that
286       you can use a QValueVector in any situation that requires an array.
287
288       See also Qt Template Library Classes, Implicitly and Explicitly Shared
289       Classes, and Non-GUI Classes.
290
291   Member Type Documentation

QValueVector::ConstIterator

293       The vector's const iterator type.
294

QValueVector::Iterator

296       The vector's iterator type.
297

QValueVector::ValueType

299       The type of the object stored in the vector.
300

QValueVector::const_iterator

302       The vector's const iterator type.
303

QValueVector::const_pointer

305       The const pointer to T type.
306

QValueVector::const_reference

308       The const reference to T type.
309

QValueVector::difference_type

311       A signed integral type used to represent the distance between two
312       iterators.
313

QValueVector::iterator

315       The vector's iterator type.
316

QValueVector::pointer

318       The pointer to T type.
319

QValueVector::reference

321       The reference to T type.
322

QValueVector::size_type

324       An unsigned integral type, used to represent various sizes.
325

QValueVector::value_type

327       The type of the object stored in the vector.
328

MEMBER FUNCTION DOCUMENTATION

QValueVector::QValueVector ()

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

QValueVector::QValueVector ( const QValueVector<T> & v )

336       Constructs a copy of v.
337
338       This operation costs O(1) time because QValueVector is implicitly
339       shared.
340
341       The first modification to the vector does takes O(n) time, because the
342       elements must be copied.
343

QValueVector::QValueVector ( size_type n, const T & val = T ( ) )

345       Constructs a vector with an initial size of n elements. Each element is
346       initialized with the value of val.
347

QValueVector::QValueVector ( std::vector<T> & v )

349       Constructs a copy of v.
350

QValueVector::QValueVector ( const std::vector<T> & v )

352       This operation costs O(n) time because v is copied.
353

QValueVector::~QValueVector ()

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

void QValueVector::append ( const T & x )

362       Appends a copy of x to the end of the vector.
363
364       See also push_back() and insert().
365

reference QValueVector::at ( size_type i, bool * ok = 0 )

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

const_reference QValueVector::at ( size_type i, bool * ok = 0 ) const

374       This is an overloaded member function, provided for convenience. It
375       behaves essentially like the above function.
376
377       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

reference QValueVector::back ()

384       Returns a reference to the last element in the vector. If there is no
385       last element, this function has undefined behavior.
386
387       See also empty() and front().
388

const_reference QValueVector::back () const

390       This is an overloaded member function, provided for convenience. It
391       behaves essentially like the above function.
392
393       Returns a const reference to the last element in the vector. If there
394       is no last element, this function has undefined behavior.
395
396       See also empty() and front().
397

iterator QValueVector::begin ()

399       Returns an iterator pointing to the beginning of the vector. If the
400       vector is empty(), the returned iterator will equal end().
401

const_iterator QValueVector::begin () const

403       This is an overloaded member function, provided for convenience. It
404       behaves essentially like the above function.
405
406       Returns a const iterator pointing to the beginning of the vector. If
407       the vector is empty(), the returned iterator will equal end().
408

size_type QValueVector::capacity () const

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

void QValueVector::clear ()

415       Removes all the elements from the vector.
416

const_iterator QValueVector::constBegin () const

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
421       See also constEnd().
422

const_iterator QValueVector::constEnd () const

424       Returns a const iterator pointing behind the last element of the
425       vector.
426
427       See also constBegin().
428

size_type QValueVector::count () const

430       Returns the number of items in the vector.
431
432       See also isEmpty().
433

bool QValueVector::empty () const

435       Returns TRUE if the vector is empty; otherwise returns FALSE.
436       Equivalent to size()==0, only faster.
437
438       This function is provided for STL compatibility. It is equivalent to
439       isEmpty().
440
441       See also size().
442

iterator QValueVector::end ()

444       Returns an iterator pointing behind the last element of the vector.
445

const_iterator QValueVector::end () const

447       This is an overloaded member function, provided for convenience. It
448       behaves essentially like the above function.
449
450       Returns a const iterator pointing behind the last element of the
451       vector.
452

iterator QValueVector::erase ( iterator pos )

454       Removes the element at position pos and returns the position of the
455       next element.
456

iterator QValueVector::erase ( iterator first, iterator last )

458       This is an overloaded member function, provided for convenience. It
459       behaves essentially like the above function.
460
461       Removes all elements from first up to but not including last and
462       returns the position of the next element.
463

reference QValueVector::first ()

465       Returns a reference to the first item in the vector. If there is no
466       first item, this function has undefined behavior.
467
468       See also empty() and last().
469

const_reference QValueVector::first () const

471       This is an overloaded member function, provided for convenience. It
472       behaves essentially like the above function.
473

reference QValueVector::front ()

475       Returns a reference to the first element in the vector. If there is no
476       first element, this function has undefined behavior.
477
478       See also empty() and back().
479

const_reference QValueVector::front () const

481       This is an overloaded member function, provided for convenience. It
482       behaves essentially like the above function.
483
484       Returns a const reference to the first element in the vector. If there
485       is no first element, this function has undefined behavior.
486
487       See also empty() and back().
488

iterator QValueVector::insert ( iterator pos, const T & x )

490       Inserts a copy of x at the position immediately before pos.
491
492       See also push_back().
493

iterator QValueVector::insert ( iterator pos, size_type n, const T & x )

495       This is an overloaded member function, provided for convenience. It
496       behaves essentially like the above function.
497
498       Inserts n copies of x immediately before position x.
499
500       See also push_back().
501

bool QValueVector::isEmpty () const

503       Returns TRUE if the vector is empty; returns FALSE otherwise.
504
505       See also count().
506

reference QValueVector::last ()

508       Returns a reference to the last item in the vector. If there is no last
509       item, this function has undefined behavior.
510
511       See also empty() and first().
512

const_reference QValueVector::last () const

514       This is an overloaded member function, provided for convenience. It
515       behaves essentially like the above function.
516

QValueVector<T> & QValueVector::operator= ( const QValueVector<T> & v )

518       Assigns v to this vector and returns a reference to this vector.
519
520       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

QValueVector<T> & QValueVector::operator= ( const std::vector<T> & v )

525       This is an overloaded member function, provided for convenience. It
526       behaves essentially like the above function.
527
528       Assigns v to this vector and returns a reference to this vector.
529
530       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

bool QValueVector::operator== ( const QValueVector<T> & x ) const

534       Returns TRUE if each element in this vector equals each corresponding
535       element in x; otherwise returns FALSE.
536

bool QValueVector::operator== ( const QValueVector<T> & x )

538       This is an overloaded member function, provided for convenience. It
539       behaves essentially like the above function.
540
541       Returns TRUE if each element in this vector equals each corresponding
542       element in x; otherwise returns FALSE.
543

reference QValueVector::operator[] ( size_type i )

545       Returns a reference to the element at index i. If i is out of range,
546       this function has undefined behavior.
547
548       See also at().
549

const_reference QValueVector::operator[] ( size_type i ) const

551       This is an overloaded member function, provided for convenience. It
552       behaves essentially like the above function.
553
554       Returns a const reference to the element at index i. If i is out of
555       range, this function has undefined behavior.
556
557       See also at().
558

void QValueVector::pop_back ()

560       Removes the last item from the vector.
561
562       This function is provided for STL compatibility.
563

void QValueVector::push_back ( const T & x )

565       Appends a copy of x to the end of the vector. This is the fastest way
566       to add new elements.
567
568       This function is provided for STL compatibility. It is equivalent to
569       append().
570
571       See also insert().
572

void QValueVector::reserve ( size_type n )

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

void QValueVector::resize ( size_type n, const T & val = T ( ) )

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

size_type QValueVector::size () const

587       Returns the number of elements in the vector.
588
589       This function is provided for STL compatibility. It is equivalent to
590       count().
591
592       See also empty().
593
594

SEE ALSO

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

AUTHOR

605       Generated automatically from the source code.
606

BUGS

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
612       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
618       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).
621
622
623
624Trolltech AS                    2 February 2007              QValueVector(3qt)
Impressum