Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \class QVarLengthArray
++ \inmodule QtCore
++ \brief The QVarLengthArray class provides a low-level variable-length array.
++
++ \ingroup tools
++ \ingroup containers
++ \reentrant
++
++ The C++ language doesn't support variable-length arrays on the stack.
++ For example, the following code won't compile:
++
++ \snippet code/doc_src_qvarlengtharray.cpp 0
++
++ The alternative is to allocate the array on the heap (with
++ \c{new}):
++
++ \snippet 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 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. The template parameter \a T specifies the element type
++ and \a Prealloc specifies how many elements to preallocate on the
++ stack; if omitted, \a Prealloc defaults to 256.
++
++ 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 QList, provides a resizable array data
++ structure. The main differences between the two classes are:
++
++ \list
++ \li QVarLengthArray's API is much more low-level and it lacks
++ some of QList's functionality.
++
++ \li QVarLengthArray doesn't initialize the memory if the value is
++ a basic type. (QList always does.)
++
++ \li QList 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 QList
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray()
++
++ Constructs an array with an initial size of zero.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(qsizetype 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 template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(qsizetype size, const T &v)
++ \since 6.4
++
++ Constructs an array with an initial size of \a size elements filled with
++ copies of \a v.
++
++ \note This constructor is only available when \c T is copy-constructible.
++
++ \sa size(), squeeze()
++ */
++
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(std::initializer_list<T> args)
++ \since 5.5
++
++ Constructs an array from the std::initializer_list given by \a args.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> template<typename InputIterator, QVarLengthArray<T, Prealloc>::if_input_iterator<InputIterator>> QVarLengthArray<T, Prealloc>::QVarLengthArray(InputIterator first, InputIterator last)
++ \since 5.14
++
++ Constructs an array with the contents in the iterator range [\a first, \a last).
++
++ The value type of \c InputIterator must be convertible to \c T.
++
++ \constraints
++ \c InputIterator meets the requirements of an
++ \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
++ */
++
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::~QVarLengthArray()
++
++ Destroys the array.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::size() const
++
++ Returns the number of elements in the array.
++
++ \sa isEmpty(), resize()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::count() const
++
++ Same as size().
++
++ \sa isEmpty(), resize()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::length() const
++ \since 5.0
++
++ Same as size().
++
++ \sa isEmpty(), resize()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::max_size() const
++ \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::maxSize()
++ \since 6.8
++
++ It returns the maximum number of elements that the array can
++ theoretically hold. In practice, the number can be much smaller,
++ limited by the amount of memory available to the system.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::first()
++
++ Returns a reference to the first item in the array. The array must
++ not be empty. If the array can be empty, check isEmpty() before
++ calling this function.
++
++ \sa last(), isEmpty()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::first() const
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::front()
++ \since 5.0
++
++ Same as first(). Provided for STL-compatibility.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::front() const
++ \since 5.0
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::last()
++
++ Returns a reference to the last item in the array. The array must
++ not be empty. If the array can be empty, check isEmpty() before
++ calling this function.
++
++ \sa first(), isEmpty()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::last() const
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T& QVarLengthArray<T, Prealloc>::back()
++ \since 5.0
++
++ Same as last(). Provided for STL-compatibility.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T& QVarLengthArray<T, Prealloc>::back() const
++ \since 5.0
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::shrink_to_fit()
++ \since 5.10
++
++ Same as squeeze(). Provided for STL-compatibility.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> bool QVarLengthArray<T, Prealloc>::isEmpty() const
++
++ Returns \c true if the array has size 0; otherwise returns \c false.
++
++ \sa size(), resize()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> bool QVarLengthArray<T, Prealloc>::empty() const
++ \since 5.0
++
++ Returns \c true if the array has size 0; otherwise returns \c false.
++
++ Same as isEmpty(). Provided for STL-compatibility.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::clear()
++
++ Removes all the elements from the array.
++
++ Same as resize(0).
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::resize(qsizetype 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(), squeeze()
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::resize(qsizetype size, const T &v)
++ \since 6.4
++
++ Sets the size of the array to \a size. If \a size is greater than
++ the current size, copies of \a v are added to the end. If \a size is
++ less than the current size, elements are removed from the end.
++
++ \note This function is only available when \c T is copy-constructible.
++
++ \sa size(), squeeze()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::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(), squeeze()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::reserve(qsizetype 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(), squeeze()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::squeeze()
++ \since 5.1
++
++ Releases any memory not required to store the items.
++ If the container can fit its storage on the stack allocation,
++ it will free the heap allocation and copy the elements back to the stack.
++
++ 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.
++
++ \sa reserve(), capacity(), resize()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T &QVarLengthArray<T, Prealloc>::operator[](qsizetype i)
++
++ Returns a reference to the item at index position \a i.
++
++ //! [valid-i]
++ \a i must be a valid index position in the array (i.e., 0 <= \a i
++ < size()).
++ //! [valid-i]
++
++ \sa data(), at()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T &QVarLengthArray<T, Prealloc>::operator[](qsizetype i) const
++
++ \overload
++ */
++
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(const T &t)
++
++ Appends item \a t to the array, extending the array if necessary.
++
++ \sa removeLast()
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::push_back(const T &t)
++ \since 5.0
++
++ Appends item \a t to the array, extending the array if necessary.
++ Provided for STL-compatibility.
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(T &&t)
++ \overload append
++ \since 5.9
++
++ \note Unlike the lvalue overload of append(), passing a reference to
++ an object that is already an element of \c *this leads to undefined
++ behavior:
++
++ \code
++ vla.append(std::move(vla[0])); // BUG: passing an object that is already in the container
++ \endcode
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::push_back(T &&t)
++ \overload push_back
++ \since 5.9
++
++ \note Unlike the lvalue overload of push_back(), passing a reference to
++ an object that is already an element of \c *this leads to undefined
++ behavior:
++
++ \code
++ vla.push_back(std::move(vla[0])); // BUG: passing an object that is already in the container
++ \endcode
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> inline void QVarLengthArray<T, Prealloc>::removeLast()
++ \since 4.5
++
++ Decreases the size of the array by one. The allocated size is not changed.
++
++ \sa append()
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::pop_back()
++ \since 5.0
++
++ Same as removeLast(). Provided for STL-compatibility.
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::append(const T *buf, qsizetype size)
++
++ Appends \a size amount of items referenced by \a buf to this array.
++ */
++
++
++ /*! \fn template<class T, qsizetype Prealloc> T *QVarLengthArray<T, Prealloc>::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 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 template<class T, qsizetype Prealloc> const T *QVarLengthArray<T, Prealloc>::data() const
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T *QVarLengthArray<T, Prealloc>::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 template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(const QVarLengthArray<T, Prealloc> &other)
++ Assigns \a other to this array and returns a reference to this array.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(QVarLengthArray<T, Prealloc> &&other)
++ Move-assigns \a other to this array and returns a reference to this array.
++ After the move, \a other is empty.
++ \since 6.0
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator=(std::initializer_list<T> list)
++ \since 5.5
++
++ Assigns the values of \a list to this array, and returns a reference to this array.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other)
++ Constructs a copy of \a other.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(QVarLengthArray<T, Prealloc> &&other)
++ Move-constructs this variable-length array from \a other. After the move, \a other is empty.
++ \since 6.0
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> const T &QVarLengthArray<T, Prealloc>::at(qsizetype i) const
++
++ Returns a reference to the item at index position \a i.
++
++ \include qvarlengtharray.qdoc valid-i
++
++ \sa value(), operator[]()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> T QVarLengthArray<T, Prealloc>::value(qsizetype 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 template<class T, qsizetype Prealloc> T QVarLengthArray<T, Prealloc>::value(qsizetype i, const T &defaultValue) const
++
++ \overload
++
++ If the index \a i is out of bounds, the function returns
++ \a defaultValue.
++ */
++
++ /*
++ \var QVarLengthArray::PreallocatedSize
++ \since 6.8
++
++ The same value as the \c{Prealloc} template argument. Provided for easier
++ access compared to manually extracting the value from the template
++ argument.
++ */
++
++ /*!
++ \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.
++ */
++
++ /*!
++ \typedef QVarLengthArray::const_iterator
++ \since 4.7
++
++ Typedef for const T *. Provided for STL compatibility.
++ */
++
++ /*!
++ \typedef QVarLengthArray::iterator
++ \since 4.7
++
++ Typedef for T *. Provided for STL compatibility.
++ */
++
++ /*!
++ \typedef QVarLengthArray::const_reverse_iterator
++ \since 5.6
++
++ Typedef for \c{std::reverse_iterator<const T*>}. Provided for STL compatibility.
++ */
++
++ /*!
++ \typedef QVarLengthArray::reverse_iterator
++ \since 5.6
++
++ Typedef for \c{std::reverse_iterator<T*>}. Provided for STL compatibility.
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::prepend(const T &value)
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::prepend(T &&value)
++
++ \since 4.8
++ \deprecated [6.3] This is slow. If you must, use \c{insert(cbegin(), ~~~)} instead.
++
++ 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 std::list instead.
++
++ \sa append(), insert()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::replace(qsizetype i, const T &value)
++
++ \since 4.8
++ Replaces the item at index position \a i with \a value.
++
++ \include qvarlengtharray.qdoc valid-i
++
++ \sa operator[](), remove()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::remove(qsizetype i, qsizetype count)
++
++ \overload
++ \since 4.8
++
++ Removes \a count elements from the array, starting at
++ index position \a i.
++
++ \include qvarlengtharray.qdoc valid-i
++ \a count must be <= size() - \a i.
++ \a i == size() is allowed if \a count == 0.
++
++ \sa insert(), replace()
++ */
++
++ /*!
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::removeAt(qsizetype i)
++ \since 6.12
++
++ Removes the element at position \a i from the array.
++
++ \include qvarlengtharray.qdoc valid-i
++
++ This function is provided for compatibility with QList.
++
++ \sa insert(), replace()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::begin()
++ \since 4.8
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
++ the array.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::begin() const
++ \since 4.8
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::cbegin() const
++ \since 5.0
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the array.
++
++ \sa begin(), cend()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::constBegin() const
++ \since 4.8
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
++ in the array.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::end()
++ \since 4.8
++
++ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
++ after the last item in the array.
++
++ \sa begin(), constEnd()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::end() const
++ \since 4.8
++
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::cend() const
++ \since 5.0
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ item after the last item in the array.
++
++ \sa cbegin(), end()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_iterator QVarLengthArray<T, Prealloc>::constEnd() const
++ \since 4.8
++
++ Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
++ item after the last item in the array.
++
++ \sa constBegin(), end()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::reverse_iterator QVarLengthArray<T, Prealloc>::rbegin()
++ \since 5.6
++
++ Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
++ item in the variable length array, in reverse order.
++
++ \sa begin(), crbegin(), rend()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::rbegin() const
++ \since 5.6
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::crbegin() const
++ \since 5.6
++
++ Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
++ item in the variable length array, in reverse order.
++
++ \sa begin(), rbegin(), rend()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::reverse_iterator QVarLengthArray<T, Prealloc>::rend()
++ \since 5.6
++
++ Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
++ the last item in the variable length array, in reverse order.
++
++ \sa end(), crend(), rbegin()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::rend() const
++ \since 5.6
++ \overload
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::const_reverse_iterator QVarLengthArray<T, Prealloc>::crend() const
++ \since 5.6
++
++ Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one
++ past the last item in the variable length array, in reverse order.
++
++ \sa end(), rend(), rbegin()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::erase(const_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 template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::erase(const_iterator begin, const_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 template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, const T &value)
++ \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, 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 std::list
++ instead.
++
++ \sa remove()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::insert(qsizetype i, qsizetype count, const T &value)
++
++ \overload
++ \since 4.8
++
++ Inserts \a count copies of \a value at index position \a i in the
++ vector.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, const T &value)
++ \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, 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 template <class T, qsizetype Prealloc> template <typename...Args> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::emplace(const_iterator pos, Args &&...args)
++
++ \since 6.3
++
++ Inserts an item in front of the item pointed to by the iterator
++ \a pos, passing \a args to its constructor.
++
++ Returns an iterator pointing at the emplaced item.
++ */
++
++ /*!
++ \fn template <class T, qsizetype Prealloc> template <typename...Args> T &QVarLengthArray<T, Prealloc>::emplace_back(Args &&...args)
++ \since 6.3
++
++ Inserts an item at the back of this QVarLengthArray, passing
++ \a args to its constructor.
++
++ Returns a reference to the emplaced item.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::iterator QVarLengthArray<T, Prealloc>::insert(const_iterator before, qsizetype 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 template<class T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
++
++ \relates QVarLengthArray
++ \since 4.8
++ Returns \c true if the two arrays, specified by \a left and \a right, are
++ equal. The preallocation sizes \a Prealloc1 and \a Prealloc2 may differ.
++
++ 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!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)}{operator!=()}
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator!=(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)
++
++ \relates QVarLengthArray
++ \since 4.8
++ Returns \c true if the two arrays, specified by \a left and \a right, are
++ \e not equal. The preallocation sizes \a Prealloc1 and \a Prealloc2 may
++ differ.
++
++ 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==(const QVarLengthArray<T, Prealloc1> &left, const QVarLengthArray<T, Prealloc2> &right)}{operator==()}
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator<(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
++ \since 5.6
++ \relates QVarLengthArray
++
++ Returns \c true if variable length array \a lhs is
++ {lexicographically less than} \a rhs; otherwise returns \c false. The
++ preallocation sizes \a Prealloc1 and \a Prealloc2 may differ.
++
++ This function requires the value type to have an implementation
++ of \c operator<().
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator<=(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
++ \since 5.6
++ \relates QVarLengthArray
++
++ Returns \c true if variable length array \a lhs is
++ {lexicographically less than or equal to} \a rhs; otherwise returns
++ \c false. The preallocation sizes \a Prealloc1 and \a Prealloc2 may differ.
++
++ This function requires the value type to have an implementation
++ of \c operator<().
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator>(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
++ \since 5.6
++ \relates QVarLengthArray
++
++ Returns \c true if variable length array \a lhs is
++ {lexicographically greater than} \a rhs; otherwise returns \c false. The
++ preallocation sizes \a Prealloc1 and \a Prealloc2 may differ.
++
++ This function requires the value type to have an implementation
++ of \c operator<().
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> bool operator>=(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
++ \since 5.6
++ \relates QVarLengthArray
++
++ Returns \c true if variable length array \a lhs is
++ {lexicographically greater than or equal to} \a rhs; otherwise returns
++ \c false. The preallocation sizes \a Prealloc1 and \a Prealloc2 may differ.
++
++ This function requires the value type to have an implementation
++ of \c operator<().
++ */
++
++ /*! \fn template<typename T, qsizetype Prealloc1, qsizetype Prealloc2> auto operator<=>(const QVarLengthArray<T,Prealloc1> &lhs, const QVarLengthArray<T,Prealloc2> &rhs)
++ \since 6.9
++ \relates QVarLengthArray
++
++ Compares the contents of \a lhs and \a rhs
++ {lexicographically}. The preallocation sizes \a Prealloc1 and \a Prealloc2 may
++ differ. Returns the result of the strongest applicable category type, that is
++ \c {decltype(lhs[0] <=> rhs[0])} if \c {operator<=>()} is available for type
++ \c {T}; otherwise \c {std::weak_ordering}.
++
++ \note This operator is only available in C++20 mode, and when the underlying
++ type \c T models the \c {std::three_way_comparable} concept
++ or provides \c {operator<()}.
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator<<(const T &value)
++
++ \since 4.8
++ Appends \a value to the array and returns a reference to this
++ vector.
++
++ \sa append(), operator+=()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator<<(T &&value)
++ \since 5.11
++
++ \overload
++
++ \sa append(), operator+=()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator+=(const T &value)
++
++ \since 4.8
++ Appends \a value to the array and returns a reference to this vector.
++
++ \sa append(), operator<<()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc> &QVarLengthArray<T, Prealloc>::operator+=(T &&value)
++ \since 5.11
++
++ \overload
++
++ \sa append(), operator<<()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::indexOf(const AT &value, qsizetype from = 0) const
++
++ \since 5.3
++ Returns the index position of the first occurrence of \a value in
++ the array, searching forward from index position \a from.
++ Returns -1 if no item matched.
++
++ This function requires the value type to have an implementation of
++ \c operator==().
++
++ \sa lastIndexOf(), contains()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::lastIndexOf(const AT &value, qsizetype from = -1) const
++
++ \since 5.3
++ Returns the index position of the last occurrence of the value \a
++ value in the array, searching backward from index position \a
++ from. If \a from is -1 (the default), the search starts at the
++ last item. Returns -1 if no item matched.
++
++ This function requires the value type to have an implementation of
++ \c operator==().
++
++ \sa indexOf(), contains()
++ */
++
++ /*! \fn template<class T, qsizetype Prealloc> template <typename AT = T> bool QVarLengthArray<T, Prealloc>::contains(const AT &value) const
++
++ \since 5.3
++ Returns \c true if the array contains an occurrence of \a value;
++ otherwise returns \c false.
++
++ This function requires the value type to have an implementation of
++ \c operator==().
++
++ \sa indexOf(), lastIndexOf()
++ */
++
++ /*!
++ \fn template <typename T, qsizetype Prealloc> size_t qHash(const QVarLengthArray<T, Prealloc> &key, size_t seed = 0)
++ \qhasholdT{QVarLengthArray}{T}
++ \since 5.14
++
++ Returns the hash value for the \a key, using \a seed to seed the
++ calculation. The preallocation size \a Prealloc does not affect the hash.
++ */
++
++ /*! \fn template <typename T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::removeAll(const AT &t)
++ \since 6.1
++
++ Removes all elements that compare equal to \a t from the
++ array. Returns the number of elements removed, if any.
++
++ \sa removeOne()
++ */
++
++ /*! \fn template <typename T, qsizetype Prealloc> template <typename AT = T> bool QVarLengthArray<T, Prealloc>::removeOne(const AT &t)
++ \since 6.1
++
++ Removes the first element that compares equal to \a t from the
++ array. Returns whether an element was, in fact, removed.
++
++ \sa removeAll()
++ */
++
++ /*! \fn template <typename T, qsizetype Prealloc> template <typename Predicate> qsizetype QVarLengthArray<T, Prealloc>::removeIf(Predicate pred)
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the array. Returns the number of elements removed, if any.
++
++ \sa removeAll()
++ */
++
++ /*! \fn template <typename T, qsizetype Prealloc, typename AT> qsizetype erase(QVarLengthArray<T, Prealloc> &array, const AT &t)
++ \relates QVarLengthArray
++ \since 6.1
++
++ Removes all elements that compare equal to \a t from the
++ array \a array. Returns the number of elements removed, if any.
++
++ \note \a t is not allowed to be a reference to an element inside \a
++ array. If you cannot be sure that this is not the case, take a copy
++ of \a t and call this function with the copy.
++
++ \sa erase_if()
++ */
++
++ /*! \fn template <typename T, qsizetype Prealloc, typename Predicate> qsizetype erase_if(QVarLengthArray<T, Prealloc> &array, Predicate pred)
++ \relates QVarLengthArray
++ \since 6.1
++
++ Removes all elements for which the predicate \a pred returns true
++ from the list \a array. Returns the number of elements removed, if
++ any. The preallocation size \a Prealloc does not affect the operation.
++
++ \sa erase()
++ */
++
++ /*! \fn template <class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(qsizetype n, const T &t)
++ \since 6.6
++
++ Replaces the contents of this container with \a n copies of \a t.
++
++ The size of this container will be equal to \a n. This function will only
++ allocate memory if \a n exceeds the capacity of the container.
++ */
++
++ /*! \fn template <class T, qsizetype Prealloc> template <typename InputIterator, QVarLengthArray<T, Prealloc>::if_input_iterator<InputIterator>> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(InputIterator first, InputIterator last)
++ \since 6.6
++
++ Replaces the contents of this container with a copy of the elements in the
++ iterator range [\a first, \a last).
++
++ The size of this container will be equal to the number of elements in the
++ range [\a first, \a last). This function will only allocate memory if the
++ number of elements in the range exceeds the capacity of the container.
++
++ The behavior is undefined if either argument is an iterator into *this.
++
++ \constraints
++ \c InputIterator meets the requirements of an
++ \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
++ */
++
++ /*! \fn template <class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>& QVarLengthArray<T, Prealloc>::assign(std::initializer_list<T> list)
++ \since 6.6
++
++ Replaces the contents of this container with a copy of the elements of \a list.
++
++ The size of this container will be equal to the number of elements in \a list.
++
++ This function only allocates memory if the number of elements in \a list
++ exceeds the capacity of the container.
++ */