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 */