--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/corelib/tools/qvarlengtharray.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,274 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** 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.qdoc 0
+
+ The alternative is to allocate the array on the heap (with
+ \c{new}):
+
+ \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 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.qdoc 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()
+*/
+
+/*! \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.qdoc 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.
+ */
+