diff options
Diffstat (limited to 'src/corelib/tools/qvarlengtharray.qdoc')
| -rw-r--r-- | src/corelib/tools/qvarlengtharray.qdoc | 214 |
1 files changed, 169 insertions, 45 deletions
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc index e454276f9d..4467e0c65a 100644 --- a/src/corelib/tools/qvarlengtharray.qdoc +++ b/src/corelib/tools/qvarlengtharray.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QVarLengthArray @@ -90,6 +66,11 @@ \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. @@ -100,21 +81,34 @@ \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. - - This constructor is only enabled if the compiler supports C++11 initializer - lists. */ -/*! \fn template<class T, qsizetype Prealloc> template<typename InputIterator> QVarLengthArray<T, Prealloc>::QVarLengthArray(InputIterator first, InputIterator last) +/*! \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). + This constructor only participates in overload resolution if + \c InputIterator meets the requirements of an + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. + The value type of \c InputIterator must be convertible to \c T. */ @@ -146,6 +140,15 @@ \sa isEmpty(), resize() */ +/*! \fn template<class T, qsizetype Prealloc> qsizetype QVarLengthArray<T, Prealloc>::max_size() + \since 6.8 + + This function is provided for STL compatibility. + 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 @@ -240,6 +243,19 @@ \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 @@ -414,9 +430,6 @@ \since 5.5 Assigns the values of \a list to this array, and returns a reference to this array. - - This constructor is only enabled if the compiler supports C++11 initializer - lists. */ /*! \fn template<class T, qsizetype Prealloc> QVarLengthArray<T, Prealloc>::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other) @@ -458,6 +471,15 @@ \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 @@ -540,6 +562,8 @@ \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. @@ -564,16 +588,6 @@ \sa operator[](), remove() */ -/*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::remove(qsizetype i) - - \overload - \since 4.8 - - Removes the element at index position \a i. - - \sa insert(), replace() -*/ - /*! \fn template<class T, qsizetype Prealloc> void QVarLengthArray<T, Prealloc>::remove(qsizetype i, qsizetype count) \overload @@ -753,6 +767,27 @@ \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 @@ -775,7 +810,7 @@ This function requires the value type to have an implementation of \c operator==(). - \sa 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) @@ -790,7 +825,7 @@ This function requires the value type to have an implementation of \c operator==(). - \sa 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) @@ -921,3 +956,92 @@ Returns the hash value for \a key, using \a seed to seed the calculation. */ + +/*! \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. + + \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. + + This function overload only participates in overload resolution if + \c InputIterator meets the requirements of an + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. + + The behavior is undefined if either argument is an iterator into *this. +*/ + +/*! \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. +*/ |