1 files changed, 547 insertions, 0 deletions
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc
new file mode 100644
index 0000000000..3c80c1cbbd
--- /dev/null
+++ b/src/corelib/tools/qvarlengtharray.qdoc
@@ -0,0 +1,547 @@
+/****************************************************************************
+**
+** 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$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $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.
+*/
+
+/*! \fn void QVarLengthArray::prepend(const T &value)
+
+    \since 4.8
+    Inserts \a value at the beginning of the array.
+
+
+    This is the same as vector.insert(0, \a value).
+
+    For large arrays, this operation can be slow (\l{linear time}),
+    because it requires moving all the items in the vector by one
+    position further in memory. If you want a container class that
+    provides a fast prepend() function, use QList or QLinkedList
+    instead.
+
+    \sa append(), insert()
+*/
+
+/*! \fn void QVarLengthArray::replace(int i, const T &value)
+
+    \since 4.8
+    Replaces the item at index position \a i with \a value.
+
+    \a i must be a valid index position in the array (i.e., 0 <= \a
+    i < size()).
+
+    \sa operator[](), remove()
+*/
+
+/*! \fn void QVarLengthArray::remove(int i)
+
+    \overload
+    \since 4.8
+
+    Removes the element at index position \a i.
+
+    \sa insert(), replace()
+*/
+
+/*! \fn void QVarLengthArray::remove(int i, int count)
+
+    \overload
+    \since 4.8
+
+    Removes \a count elements from the middle of the array, starting at
+    index position \a i.
+
+    \sa insert(), replace()
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::begin()
+    \since 4.8
+
+    Returns an \l{STL-style iterator} pointing to the first item in
+    the array.
+
+    \sa constBegin(), end()
+*/
+
+/*! \fn QVarLengthArray::const_iterator QVarLengthArray::begin() const
+    \since 4.8
+    \overload
+*/
+
+/*! \fn QVarLengthArray::const_iterator QVarLengthArray::constBegin() const
+    \since 4.8
+
+    Returns a const \l{STL-style iterator} pointing to the first item
+    in the array.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::end()
+    \since 4.8
+
+    Returns an \l{STL-style iterator} pointing to the imaginary item
+    after the last item in the array.
+
+    \sa begin(), constEnd()
+*/
+
+/*! \fn QVarLengthArray::const_iterator QVarLengthArray::end() const
+    \since 4.8
+
+    \overload
+*/
+
+/*! \fn QVarLengthArray::const_iterator QVarLengthArray::constEnd() const
+    \since 4.8
+
+    Returns a const \l{STL-style iterator} pointing to the imaginary
+    item after the last item in the array.
+
+    \sa constBegin(), end()
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::erase(iterator pos)
+    \since 4.8
+
+    Removes the item pointed to by the iterator \a pos from the
+    vector, and returns an iterator to the next item in the vector
+    (which may be end()).
+
+    \sa insert(), remove()
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::erase(iterator begin, iterator end)
+
+    \overload
+    \since 4.8
+
+    Removes all the items from \a begin up to (but not including) \a
+    end. Returns an iterator to the same item that \a end referred to
+    before the call.
+*/
+
+/*! \fn void QVarLengthArray::insert(int i, const T &value)
+    \since 4.8
+
+    Inserts \a value at index position \a i in the array. If \a i is
+    0, the value is prepended to the vector. If \a i is size(), the
+    value is appended to the vector.
+
+    For large arrays, this operation can be slow (\l{linear time}),
+    because it requires moving all the items at indexes \a i and
+    above by one position further in memory. If you want a container
+    class that provides a fast insert() function, use QLinkedList
+    instead.
+
+    \sa remove()
+*/
+
+/*! \fn void QVarLengthArray::insert(int i, int count, const T &value)
+
+    \overload
+    \since 4.8
+
+    Inserts \a count copies of \a value at index position \a i in the
+    vector.
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::insert(iterator before, const T &value)
+
+    \overload
+    \since 4.8
+
+    Inserts \a value in front of the item pointed to by the iterator
+    \a before. Returns an iterator pointing at the inserted item.
+*/
+
+/*! \fn QVarLengthArray::iterator QVarLengthArray::insert(iterator before, int count, const T &value)
+
+    \since 4.8
+    Inserts \a count copies of \a value in front of the item pointed to
+    by the iterator \a before. Returns an iterator pointing at the
+    first of the inserted items.
+*/
+
+
+
+/*! \fn bool operator==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
+
+    \relates QVarLengthArray
+    \since 4.8
+    Returns true if the two array are equal;
+
+    Two arrays are considered equal if they contain the same values
+    in the same order.
+
+    This function requires the value type to have an implementation
+    of \c operator==().
+
+    \sa operator!=()
+*/
+
+/*! \fn bool operator!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
+
+    \relates QVarLengthArray
+    \since 4.8
+    Returns true if the two array are different;
+
+    Two arrays are considered equal if they contain the same values
+    in the same order.
+
+    This function requires the value type to have an implementation
+    of \c operator==().
+
+    \sa operator==()
+*/
+
+/*! \fn QVarLengthArray &QVarLengthArray::operator<<(const T &value)
+
+    \since 4.8
+    Appends \a value to the array and returns a reference to this
+    vector.
+
+    \sa append(), operator+=()
+*/
+
+/*! \fn QVarLengthArray &QVarLengthArray::operator+=(const T &value)
+
+    \since 4.8
+    Appends \a value to the array and returns a reference to this
+    vector.
+
+    \sa append(), operator<<()
+*/
+