| /**************************************************************************** |
| ** |
| ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). |
| ** All rights reserved. |
| ** Contact: Nokia Corporation (qt-info@nokia.com) |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** GNU Free Documentation License |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. |
| ** |
| ** Other Usage |
| ** Alternatively, this file may be used in accordance with the terms |
| ** and conditions contained in a signed written agreement between you |
| ** and Nokia. |
| ** |
| ** |
| ** |
| ** |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \class QVarLengthArray |
| \brief The QVarLengthArray class provides a low-level variable-length array. |
| |
| \ingroup tools |
| \reentrant |
| |
| The C++ language doesn't support variable-length arrays on the stack. |
| For example, the following code won't compile: |
| |
| \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 0 |
| |
| The alternative is to allocate the array on the heap (with |
| \c{new}): |
| |
| \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 1 |
| |
| However, if myfunc() is called very frequently from the |
| application's inner loop, heap allocation can be a major source |
| of slowdown. |
| |
| QVarLengthArray is an attempt to work around this gap in the C++ |
| language. It allocates a certain number of elements on the stack, |
| and if you resize the array to a larger size, it automatically |
| uses the heap instead. Stack allocation has the advantage that |
| it is much faster than heap allocation. |
| |
| Example: |
| \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 2 |
| |
| In the example above, QVarLengthArray will preallocate 1024 |
| elements on the stack and use them unless \c{n + 1} is greater |
| than 1024. If you omit the second template argument, |
| QVarLengthArray's default of 256 is used. |
| |
| QVarLengthArray's value type must be an \l{assignable data type}. |
| This covers most data types that are commonly used, but the |
| compiler won't let you, for example, store a QWidget as a value; |
| instead, store a QWidget *. |
| |
| QVarLengthArray, like QVector, provides a resizable array data |
| structure. The main differences between the two classes are: |
| |
| \list |
| \o QVarLengthArray's API is much more low-level. It provides no |
| iterators and lacks much of QVector's functionality. |
| |
| \o QVarLengthArray doesn't initialize the memory if the value is |
| a basic type. (QVector always does.) |
| |
| \o QVector uses \l{implicit sharing} as a memory optimization. |
| QVarLengthArray doesn't provide that feature; however, it |
| usually produces slightly better performance due to reduced |
| overhead, especially in tight loops. |
| \endlist |
| |
| In summary, QVarLengthArray is a low-level optimization class |
| that only makes sense in very specific cases. It is used a few |
| places inside Qt and was added to Qt's public API for the |
| convenience of advanced users. |
| |
| \sa QVector, QList, QLinkedList |
| */ |
| |
| /*! \fn QVarLengthArray::QVarLengthArray(int size) |
| |
| Constructs an array with an initial size of \a size elements. |
| |
| If the value type is a primitive type (e.g., char, int, float) or |
| a pointer type (e.g., QWidget *), the elements are not |
| initialized. For other types, the elements are initialized with a |
| \l{default-constructed value}. |
| */ |
| |
| /*! \fn QVarLengthArray::~QVarLengthArray() |
| |
| Destroys the array. |
| */ |
| |
| /*! \fn int QVarLengthArray::size() const |
| |
| Returns the number of elements in the array. |
| |
| \sa isEmpty(), resize() |
| */ |
| |
| /*! \fn int QVarLengthArray::count() const |
| |
| Same as size(). |
| |
| \sa isEmpty(), resize() |
| */ |
| |
| /*! \fn bool QVarLengthArray::isEmpty() const |
| |
| Returns true if the array has size 0; otherwise returns false. |
| |
| \sa size(), resize() |
| */ |
| |
| /*! \fn void QVarLengthArray::clear() |
| |
| Removes all the elements from the array. |
| |
| Same as resize(0). |
| */ |
| |
| /*! \fn void QVarLengthArray::resize(int size) |
| |
| Sets the size of the array to \a size. If \a size is greater than |
| the current size, elements are added to the end. If \a size is |
| less than the current size, elements are removed from the end. |
| |
| If the value type is a primitive type (e.g., char, int, float) or |
| a pointer type (e.g., QWidget *), new elements are not |
| initialized. For other types, the elements are initialized with a |
| \l{default-constructed value}. |
| |
| \sa size() |
| */ |
| |
| /*! \fn int QVarLengthArray::capacity() const |
| |
| Returns the maximum number of elements that can be stored in the |
| array without forcing a reallocation. |
| |
| The sole purpose of this function is to provide a means of fine |
| tuning QVarLengthArray's memory usage. In general, you will rarely ever |
| need to call this function. If you want to know how many items are |
| in the array, call size(). |
| |
| \sa reserve() |
| */ |
| |
| /*! \fn void QVarLengthArray::reserve(int size) |
| |
| Attempts to allocate memory for at least \a size elements. If you |
| know in advance how large the array can get, you can call this |
| function and if you call resize() often, you are likely to get |
| better performance. If \a size is an underestimate, the worst |
| that will happen is that the QVarLengthArray will be a bit |
| slower. |
| |
| The sole purpose of this function is to provide a means of fine |
| tuning QVarLengthArray's memory usage. In general, you will |
| rarely ever need to call this function. If you want to change the |
| size of the array, call resize(). |
| |
| \sa capacity() |
| */ |
| |
| /*! \fn T &QVarLengthArray::operator[](int i) |
| |
| Returns a reference to the item at index position \a i. |
| |
| \a i must be a valid index position in the array (i.e., 0 <= \a i |
| < size()). |
| |
| \sa data(), at() |
| */ |
| |
| /*! \fn const T &QVarLengthArray::operator[](int i) const |
| |
| \overload |
| */ |
| |
| |
| /*! |
| \fn void QVarLengthArray::append(const T &t) |
| |
| Appends item \a t to the array, extending the array if necessary. |
| |
| \sa removeLast() |
| */ |
| |
| |
| /*! |
| \fn inline void QVarLengthArray::removeLast() |
| \since 4.5 |
| |
| Decreases the size of the array by one. The allocated size is not changed. |
| |
| \sa append() |
| */ |
| |
| /*! |
| \fn void QVarLengthArray::append(const T *buf, int size) |
| |
| Appends \a size amount of items referenced by \a buf to this array. |
| */ |
| |
| |
| /*! \fn T *QVarLengthArray::data() |
| |
| Returns a pointer to the data stored in the array. The pointer can |
| be used to access and modify the items in the array. |
| |
| Example: |
| \snippet doc/src/snippets/code/doc_src_qvarlengtharray.cpp 3 |
| |
| The pointer remains valid as long as the array isn't reallocated. |
| |
| This function is mostly useful to pass an array to a function |
| that accepts a plain C++ array. |
| |
| \sa constData(), operator[]() |
| */ |
| |
| /*! \fn const T *QVarLengthArray::data() const |
| |
| \overload |
| */ |
| |
| /*! \fn const T *QVarLengthArray::constData() const |
| |
| Returns a const pointer to the data stored in the array. The |
| pointer can be used to access the items in the array. The |
| pointer remains valid as long as the array isn't reallocated. |
| |
| This function is mostly useful to pass an array to a function |
| that accepts a plain C++ array. |
| |
| \sa data(), operator[]() |
| */ |
| |
| /*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other) |
| Assigns \a other to this array and returns a reference to this array. |
| */ |
| |
| /*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other) |
| Constructs a copy of \a other. |
| */ |
| |
| /*! \fn const T &QVarLengthArray::at(int i) const |
| |
| Returns a reference to the item at index position \a i. |
| |
| \a i must be a valid index position in the array (i.e., 0 <= \a i |
| < size()). |
| |
| \sa value(), operator[]() |
| */ |
| |
| /*! \fn T QVarLengthArray::value(int i) const |
| |
| Returns the value at index position \a i. |
| |
| If the index \a i is out of bounds, the function returns |
| a \l{default-constructed value}. If you are certain that |
| \a i is within bounds, you can use at() instead, which is slightly |
| faster. |
| |
| \sa at(), operator[]() |
| */ |
| |
| /*! \fn T QVarLengthArray::value(int i, const T &defaultValue) const |
| |
| \overload |
| |
| If the index \a i is out of bounds, the function returns |
| \a defaultValue. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::size_type |
| \since 4.7 |
| |
| Typedef for int. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::value_type |
| \since 4.7 |
| |
| Typedef for T. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::difference_type |
| \since 4.7 |
| |
| Typedef for ptrdiff_t. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::pointer |
| \since 4.7 |
| |
| Typedef for T *. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::const_pointer |
| \since 4.7 |
| |
| Typedef for const T *. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::reference |
| \since 4.7 |
| |
| Typedef for T &. Provided for STL compatibility. |
| */ |
| |
| /*! |
| \typedef QVarLengthArray::const_reference |
| \since 4.7 |
| |
| Typedef for const T &. Provided for STL compatibility. |
| */ |
| |