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 QVarLengthArray

    44     \brief The QVarLengthArray class provides a low-level variable-length array.

    45 

    46     \ingroup tools

    47     \reentrant

    48 

    49     The C++ language doesn't support variable-length arrays on the stack.

    50     For example, the following code won't compile:

    51 

    52     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0

    53 

    54     The alternative is to allocate the array on the heap (with

    55     \c{new}):

    56 

    57     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1

    58 

    59     However, if myfunc() is called very frequently from the

    60     application's inner loop, heap allocation can be a major source

    61     of slowdown.

    62 

    63     QVarLengthArray is an attempt to work around this gap in the C++

    64     language. It allocates a certain number of elements on the stack,

    65     and if you resize the array to a larger size, it automatically

    66     uses the heap instead. Stack allocation has the advantage that

    67     it is much faster than heap allocation.

    68 

    69     Example:

    70     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2

    71 

    72     In the example above, QVarLengthArray will preallocate 1024

    73     elements on the stack and use them unless \c{n + 1} is greater

    74     than 1024. If you omit the second template argument,

    75     QVarLengthArray's default of 256 is used.

    76 

    77     QVarLengthArray's value type must be an \l{assignable data type}.

    78     This covers most data types that are commonly used, but the

    79     compiler won't let you, for example, store a QWidget as a value;

    80     instead, store a QWidget *.

    81 

    82     QVarLengthArray, like QVector, provides a resizable array data

    83     structure. The main differences between the two classes are:

    84 

    85     \list

    86     \o QVarLengthArray's API is much more low-level. It provides no

    87        iterators and lacks much of QVector's functionality.

    88 

    89     \o QVarLengthArray doesn't initialize the memory if the value is

    90        a basic type. (QVector always does.)

    91 

    92     \o QVector uses \l{implicit sharing} as a memory optimization.

    93        QVarLengthArray doesn't provide that feature; however, it

    94        usually produces slightly better performance due to reduced

    95        overhead, especially in tight loops.

    96     \endlist

    97 

    98     In summary, QVarLengthArray is a low-level optimization class

    99     that only makes sense in very specific cases. It is used a few

   100     places inside Qt and was added to Qt's public API for the

   101     convenience of advanced users.

   102 

   103     \sa QVector, QList, QLinkedList

   104 */

   105 

   106 /*! \fn QVarLengthArray::QVarLengthArray(int size)

   107 

   108     Constructs an array with an initial size of \a size elements.

   109 

   110     If the value type is a primitive type (e.g., char, int, float) or

   111     a pointer type (e.g., QWidget *), the elements are not

   112     initialized. For other types, the elements are initialized with a

   113     \l{default-constructed value}.

   114 */

   115 

   116 /*! \fn QVarLengthArray::~QVarLengthArray()

   117 

   118     Destroys the array.

   119 */

   120 

   121 /*! \fn int QVarLengthArray::size() const

   122 

   123     Returns the number of elements in the array.

   124 

   125     \sa isEmpty(), resize()

   126 */

   127 

   128 /*! \fn int QVarLengthArray::count() const

   129 

   130     Same as size().

   131 

   132     \sa isEmpty(), resize()

   133 */

   134 

   135 /*! \fn bool QVarLengthArray::isEmpty() const

   136 

   137     Returns true if the array has size 0; otherwise returns false.

   138 

   139     \sa size(), resize()

   140 */

   141 

   142 /*! \fn void QVarLengthArray::clear()

   143 

   144     Removes all the elements from the array.

   145 

   146     Same as resize(0).

   147 */

   148 

   149 /*! \fn void QVarLengthArray::resize(int size)

   150 

   151     Sets the size of the array to \a size. If \a size is greater than

   152     the current size, elements are added to the end. If \a size is

   153     less than the current size, elements are removed from the end.

   154 

   155     If the value type is a primitive type (e.g., char, int, float) or

   156     a pointer type (e.g., QWidget *), new elements are not

   157     initialized. For other types, the elements are initialized with a

   158     \l{default-constructed value}.

   159 

   160     \sa size()

   161 */

   162 

   163 /*! \fn int QVarLengthArray::capacity() const

   164 

   165     Returns the maximum number of elements that can be stored in the

   166     array without forcing a reallocation.

   167 

   168     The sole purpose of this function is to provide a means of fine

   169     tuning QVarLengthArray's memory usage. In general, you will rarely ever

   170     need to call this function. If you want to know how many items are

   171     in the array, call size().

   172 

   173     \sa reserve()

   174 */

   175 

   176 /*! \fn void QVarLengthArray::reserve(int size)

   177 

   178     Attempts to allocate memory for at least \a size elements. If you

   179     know in advance how large the array can get, you can call this

   180     function and if you call resize() often, you are likely to get

   181     better performance. If \a size is an underestimate, the worst

   182     that will happen is that the QVarLengthArray will be a bit

   183     slower.

   184 

   185     The sole purpose of this function is to provide a means of fine

   186     tuning QVarLengthArray's memory usage. In general, you will

   187     rarely ever need to call this function. If you want to change the

   188     size of the array, call resize().

   189 

   190     \sa capacity()

   191 */

   192 

   193 /*! \fn T &QVarLengthArray::operator[](int i)

   194 

   195     Returns a reference to the item at index position \a i.

   196 

   197     \a i must be a valid index position in the array (i.e., 0 <= \a i

   198     < size()).

   199 

   200     \sa data()

   201 */

   202 

   203 /*! \fn const T &QVarLengthArray::operator[](int i) const

   204 

   205     \overload

   206 */

   207 

   208 

   209 /*!

   210     \fn void QVarLengthArray::append(const T &t)

   211 

   212     Appends item \a t to the array, extending the array if necessary.

   213 

   214     \sa removeLast()

   215 */

   216 

   217 

   218 /*!

   219     \fn inline void QVarLengthArray::removeLast()

   220     \since 4.5

   221 

   222     Decreases the size of the array by one.  The allocated size is not changed.

   223 

   224     \sa append()

   225 */

   226 

   227 /*!

   228     \fn void QVarLengthArray::append(const T *buf, int size)

   229 

   230     Appends \a size amount of items referenced by \a buf to this array.

   231 */

   232 

   233 

   234 /*! \fn T *QVarLengthArray::data()

   235 

   236     Returns a pointer to the data stored in the array. The pointer can

   237     be used to access and modify the items in the array.

   238 

   239     Example:

   240     \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3

   241 

   242     The pointer remains valid as long as the array isn't reallocated.

   243 

   244     This function is mostly useful to pass an array to a function

   245     that accepts a plain C++ array.

   246 

   247     \sa constData(), operator[]()

   248 */

   249 

   250 /*! \fn const T *QVarLengthArray::data() const

   251 

   252     \overload

   253 */

   254 

   255 /*! \fn const T *QVarLengthArray::constData() const

   256 

   257     Returns a const pointer to the data stored in the array. The

   258     pointer can be used to access the items in the array. The

   259     pointer remains valid as long as the array isn't reallocated.

   260 

   261     This function is mostly useful to pass an array to a function

   262     that accepts a plain C++ array.

   263 

   264     \sa data(), operator[]()

   265 */

   266 

   267 /*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other)

   268     Assigns \a other to this array and returns a reference to this array.

   269  */

   270 

   271 /*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)

   272     Constructs a copy of \a other.

   273  */

   274