diff options
Diffstat (limited to 'src/corelib/tools/qlist.qdoc')
| -rw-r--r-- | src/corelib/tools/qlist.qdoc | 454 |
1 files changed, 273 insertions, 181 deletions
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc index 4a36897ae2..e07b74cd53 100644 --- a/src/corelib/tools/qlist.qdoc +++ b/src/corelib/tools/qlist.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 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) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QVector @@ -136,14 +112,14 @@ to reduce the number of reallocations by preallocating up to twice as much memory as the actual data needs. - If you know in advance approximately how many items the QList - will contain, you can call reserve(), asking QList to - preallocate a certain amount of memory. You can also call - capacity() to find out how much memory QList actually - allocated. + If you're building a QList gradually and know in advance + approximately how many elements it will contain, you can call reserve(), + asking QList to preallocate a certain amount of memory. + You can also call capacity() to find out how much memory the + QList actually has allocated. - Note that using non-const operators and functions can cause - QList to do a deep copy of the data. This is due to \l{implicit sharing}. + Note that using non-const operators and functions can cause QList + to do a deep copy of the data, due to \l{implicit sharing}. QList's value type must be an \l{assignable data type}. This covers most data types that are commonly used, but the compiler @@ -153,20 +129,12 @@ support \c operator==(). These requirements are documented on a per-function basis. - Like the other container classes, QList provides \l{Java-style - iterators} (QListIterator and QMutableListIterator) and - \l{STL-style iterators} (QList::const_iterator and - QList::iterator). In practice, these are rarely used, because - you can use indexes into the QList. + For iterating over the items, see \l {Iterating over Containers}. In addition to QList, Qt also provides QVarLengthArray, a very low-level class with little functionality that is optimized for speed. - QList does \e not support inserting, prepending, appending or replacing - with references to its own values. Doing so will cause your application to - abort with an error message. - \section2 More Information on Using Qt Containers For a detailed discussion comparing Qt containers with each other and @@ -174,16 +142,16 @@ \section1 Maximum size and out-of-memory conditions - The maximum size of QList depends on the architecture. You should be able to - use more than 2 GB of memory and you can typically expect 2^63 bytes - limitation in size on 64-bit systems. The actual value also depends on the - overhead required for managing the data block, which is no more than 32 - bytes, and extra reserved space, which is 2 bytes. The number of elements - that can be stored in a QList is this possible size divided by the size of a - stored element. + The maximum size of QList depends on the architecture. Most 64-bit + systems can allocate more than 2 GB of memory, with a typical limit + of 2^63 bytes. The actual value also depends on the overhead required for + managing the data block. As a result, you can expect the maximum size + of 2 GB minus overhead on 32-bit platforms, and 2^63 bytes minus overhead + on 64-bit platforms. The number of elements that can be stored in a + QList is this maximum size divided by the size of a stored element. - In case memory allocation fails, QList will use the \l Q_CHECK_PTR macro, - which will throw a \c std::bad_alloc exception if the application is being + When memory allocation fails, QList uses the \l Q_CHECK_PTR macro, + which throws a \c std::bad_alloc exception if the application is being compiled with exception support. If exceptions are disabled, then running out of memory is undefined behavior. @@ -279,7 +247,32 @@ \sa resize() */ -/*! \fn template <typename T> QList<T>::QList(qsizetype size, const T &value) +/*! \fn template <typename T> QList<T>::QList(qsizetype size, Qt::Initialization) + \since 6.8 + + Constructs a list with an initial size of \a size elements. + + QList will make an attempt at \b{not initializing} the elements. + +//! [qlist-uninitialized-strategy] + Specifically: + + \list + + \li if \c{T} has a constructor that accepts \c{Qt::Uninitialized}, + that constructor will be used to initialize the elements; + + \li otherwise, each element is default constructed. For + trivially constructible types (such as \c{int}, \c{float}, etc.) + this is equivalent to not initializing them. + + \endlist +//! [qlist-uninitialized-strategy] + + \sa resizeForOverwrite() +*/ + +/*! \fn template <typename T> QList<T>::QList(qsizetype size, parameter_type value) Constructs a list with an initial size of \a size elements. Each element is initialized with \a value. @@ -304,16 +297,17 @@ \since 4.8 Constructs a list from the std::initializer_list given by \a args. - - This constructor is only enabled if the compiler supports C++11 initializer - lists. */ -/*! \fn template <typename T> template<typename InputIterator> QList<T>::QList(InputIterator first, InputIterator last) +/*! \fn template<typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator> = true> QList<T>::QList(InputIterator first, InputIterator last) \since 5.14 Constructs a list with the contents in the iterator range [\a first, \a last). + \note This constructor only participates in overload resolution if + \c InputIterator meets the requirements of a + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. + The value type of \c InputIterator must be convertible to \c T. */ @@ -338,13 +332,9 @@ /*! \fn template <typename T> QList<T> &QList<T>::operator=(std::initializer_list<T> args) + \since 5.14 Assigns the collection of values in \a args to this QList instance. - - This operator is only enabled if the compiler supports C++11 initializer - lists. - - \since 5.14 */ /*! \fn template <typename T> void QList<T>::swap(QList<T> &other) @@ -391,49 +381,45 @@ \sa operator==() */ -/*! \fn template <typename T> bool operator<(const QList<T> &lhs, const QList<T> &rhs) +/*! \fn template <typename T> bool QList<T>::operator<(const QList<T> &other) const \since 5.6 - \relates QList - Returns \c true if list \a lhs is + Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically less than} \a rhs; otherwise returns \c false. + {lexically less than} \a other; otherwise returns \c false. This function requires the value type to have an implementation of \c operator<(). */ -/*! \fn template <typename T> bool operator<=(const QList<T> &lhs, const QList<T> &rhs) +/*! \fn template <typename T> bool QList<T>::operator<=(const QList<T> &other) const \since 5.6 - \relates QList - Returns \c true if list \a lhs is + Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically less than or equal to} \a rhs; otherwise returns \c false. + {lexically less than or equal to} \a other; otherwise returns \c false. This function requires the value type to have an implementation of \c operator<(). */ -/*! \fn template <typename T> bool operator>(const QList<T> &lhs, const QList<T> &rhs) +/*! \fn template <typename T> bool QList<T>::operator>(const QList<T> &other) const \since 5.6 - \relates QList - Returns \c true if list \a lhs is + Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically greater than} \a rhs; otherwise returns \c false. + {lexically greater than} \a other; otherwise returns \c false. This function requires the value type to have an implementation of \c operator<(). */ -/*! \fn template <typename T> bool operator>=(const QList<T> &lhs, const QList<T> &rhs) +/*! \fn template <typename T> bool QList<T>::operator>=(const QList<T> &other) const \since 5.6 - \relates QList - Returns \c true if list \a lhs is + Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically greater than or equal to} \a rhs; otherwise returns \c false. + {lexically greater than or equal to} \a other; otherwise returns \c false. This function requires the value type to have an implementation of \c operator<(). @@ -465,18 +451,35 @@ */ /*! \fn template <typename T> void QList<T>::resize(qsizetype size) + \fn template <typename T> void QList<T>::resize(qsizetype size, parameter_type c) + \since 6.0 Sets the size of the list to \a size. If \a size is greater than the current size, elements are added to the end; the new elements are - initialized with a \l{default-constructed value}. If \a size is less - than the current size, elements are removed from the end. + initialized with either a \l{default-constructed value} or \a c. If \a size + is less than the current size, elements are removed from the end. + + If this list is not shared, the capacity() is preserved. Use squeeze() + to shed excess capacity. - Since Qt 5.6, resize() doesn't shrink the capacity anymore. - To shed excess capacity, use squeeze(). + \note In Qt versions prior to 5.7 (for QVector; QList lacked a resize() + until 6.0), this function released the memory used by the list instead of + preserving the capacity. \sa size() */ +/*! \fn template <typename T> void QList<T>::resizeForOverwrite(qsizetype size) + \since 6.8 + + Sets the size of the list to \a size. If \a size is less than the + current size, elements are removed from the end. If \a size is + greater than the current size, elements are added to the end; QList + will make an attempt at \b{not initializing} these new elements. + + \include qlist.qdoc qlist-uninitialized-strategy +*/ + /*! \fn template <typename T> qsizetype QList<T>::capacity() const Returns the maximum number of items that can be stored in the @@ -490,36 +493,35 @@ \note a statically allocated list will report a capacity of 0, even if it's not empty. - \note The free space position in the allocated memory block is undefined. In - other words, one should not assume that the free memory is always located - after the initialized elements. + \warning The free space position in the allocated memory block is undefined. + In other words, you should not assume that the free memory is always located + at the end of the list. You can call reserve() to ensure that there is + enough space at the end. \sa reserve(), squeeze() */ /*! \fn template <typename T> void QList<T>::reserve(qsizetype size) - Attempts to allocate memory for at least \a size elements. If you - know in advance how large the list will be, you should call this - function to prevent reallocations and memory fragmentation. + Attempts to allocate memory for at least \a size elements. - If \a size is an underestimate, the worst that will happen is that - the QList will be a bit slower. If \a size is an overestimate, you - may have used more memory than the normal QList growth strategy - would have allocated—or you may have used less. + If you know in advance how large the list will be, you should call this + function to prevent reallocations and memory fragmentation. If you resize + the list often, you are also likely to get better performance. - An alternative to reserve() is calling resize(). Whether or not that is - faster than reserve() depends on the element type, because resize() - default-constructs all elements, and requires assignment to existing - entries rather than calling append(), which copy- or move-constructs. - For simple types, like \c int or \c double, resize() is typically faster, - but for anything more complex, you should prefer reserve(). + If in doubt about how much space shall be needed, it is usually better to + use an upper bound as \a size, or a high estimate of the most likely size, + if a strict upper bound would be much bigger than this. If \a size is an + underestimate, the list will grow as needed once the reserved size is + exceeded, which may lead to a larger allocation than your best overestimate + would have and will slow the operation that triggers it. - \warning If the size passed to resize() was underestimated, you run out - of allocated space and into undefined behavior. This problem does not - exist with reserve(), because it treats the size as just a hint. + \warning reserve() reserves memory but does not change the size of the + list. Accessing data beyond the current end of the list is + undefined behavior. If you need to access memory beyond the current end of + the list, use resize(). - \sa squeeze(), capacity() + \sa squeeze(), capacity(), resize() */ /*! \fn template <typename T> void QList<T>::squeeze() @@ -593,17 +595,14 @@ Removes all the elements from the list. - \note Until Qt 5.6, this also released the memory used by - the list. From Qt 5.7, the capacity is preserved. To shed - all capacity, swap with a default-constructed list: - \code - QList<T> l ...; - QList<T>().swap(l); - Q_ASSERT(l.capacity() == 0); - \endcode - or call squeeze(). + If this list is not shared, the capacity() is preserved. Use squeeze() to + shed excess capacity. + + \note In Qt versions prior to 5.7 (for QVector) and 6.0 (for QList), this + function released the memory used by the list instead of preserving the + capacity. - \sa squeeze() + \sa resize(), squeeze() */ /*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const @@ -637,7 +636,7 @@ */ /*! - \fn template <typename T> void QList<T>::append(const_reference value) + \fn template <typename T> void QList<T>::append(parameter_type value) Inserts \a value at the end of the list. @@ -686,7 +685,7 @@ */ /*! - \fn template <typename T> void QList<T>::prepend(const T &value) + \fn template <typename T> void QList<T>::prepend(parameter_type value) \fn template <typename T> void QList<T>::prepend(rvalue_ref value) Inserts \a value at the beginning of the list. @@ -696,11 +695,12 @@ This is the same as list.insert(0, \a value). - For large lists, this operation can be slow (\l{linear time}), - because it requires moving all the items in the list by one - position further in memory. If you want a container class that - provides a fast prepend operation, use std::list - instead. + Normally this operation is relatively fast (amortized \l{constant time}). + QList is able to allocate extra memory at the beginning of the list data + and grow in that direction without reallocating or moving the data on each + operation. However if you want a container class with a guarantee of + \l{constant time} prepend, use std::list instead, + but prefer QList otherwise. \sa append(), insert() */ @@ -785,7 +785,7 @@ Example: \snippet code/src_corelib_tools_qlist.cpp emplace - \note It is garanteed that the element will be created in place + \note It is guaranteed that the element will be created in place at the beginning, but after that it might be copied or moved to the right position. @@ -793,7 +793,7 @@ */ -/*! \fn template <typename T> void QList<T>::replace(qsizetype i, const T &value) +/*! \fn template <typename T> void QList<T>::replace(qsizetype i, parameter_type value) \fn template <typename T> void QList<T>::replace(qsizetype i, rvalue_ref value) Replaces the item at index position \a i with \a value. @@ -808,15 +808,15 @@ Removes \a n elements from the list, starting at index position \a i. - If too many elements are removed from the list, the list may shrink the - capacity to reduce the allocated memory size. To make sure this does not - happen, use reserve() to give a hint to the list that the capacity should be - preserved. +//! [shrinking-erase] + Element removal will preserve the list's capacity and not reduce the amount of + allocated memory. To shed extra capacity and free as much memory as possible, + call squeeze(). +//! [shrinking-erase] //! [iterator-invalidation-erase] - \note When QList is not \l{implicitly shared} and the capacity is reserved - with a call to reserve(), this function only invalidates iterators at or - after the specified position. + \note When QList is not \l{implicitly shared}, this function only + invalidates iterators at or after the specified position. //! [iterator-invalidation-erase] \sa insert(), replace(), fill() @@ -831,26 +831,40 @@ remove(i); \endcode + \include qlist.qdoc shrinking-erase \include qlist.qdoc iterator-invalidation-erase \sa remove() */ -/*! \fn template <typename T> template <typename AT> qsizetype QList<T>::removeAll(const AT &t) +/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::removeAll(const AT &t) \since 5.4 Removes all elements that compare equal to \a t from the list. Returns the number of elements removed, if any. + \include qlist.qdoc shrinking-erase + \sa removeOne() */ -/*! \fn template <typename T> template <typename AT> bool QList<T>::removeOne(const AT &t) +/*! \fn template <typename T> template <typename AT = T> bool QList<T>::removeOne(const AT &t) \since 5.4 Removes the first element that compares equal to \a t from the list. Returns whether an element was, in fact, removed. + \include qlist.qdoc shrinking-erase + + \sa removeAll() +*/ + +/*! \fn template <typename T> template <typename Predicate> qsizetype QList<T>::removeIf(Predicate pred) + \since 6.1 + + Removes all elements for which the predicate \a pred returns true + from the list. Returns the number of elements removed, if any. + \sa removeAll() */ @@ -874,6 +888,8 @@ return t; \endcode + \include qlist.qdoc iterator-invalidation-erase + \sa takeFirst(), takeLast() */ @@ -881,8 +897,6 @@ \since 5.6 Moves the item at index position \a from to index position \a to. - - \sa QList::move() */ /*! \fn template <typename T> void QList<T>::removeFirst() @@ -892,6 +906,8 @@ the list can be empty, call isEmpty() before calling this function. + \include qlist.qdoc shrinking-erase + \sa remove(), takeFirst(), isEmpty() */ @@ -902,6 +918,8 @@ empty. If the list can be empty, call isEmpty() before calling this function. + \include qlist.qdoc shrinking-erase + \sa remove(), takeLast(), removeFirst(), isEmpty() */ @@ -943,8 +961,7 @@ /*! \fn template <typename T> QList<T> &QList<T>::fill(parameter_type value, qsizetype size = -1) Assigns \a value to all items in the list. If \a size is - different from -1 (the default), the list is resized to size \a - size beforehand. + different from -1 (the default), the list is resized to \a size beforehand. Example: \snippet code/src_corelib_tools_qlist.cpp 11 @@ -952,7 +969,7 @@ \sa resize() */ -/*! \fn template <typename T> qsizetype QList<T>::indexOf(const T &value, qsizetype from = 0) const +/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::indexOf(const AT &value, qsizetype from = 0) const Returns the index position of the first occurrence of \a value in the list, searching forward from index position \a from. @@ -967,7 +984,7 @@ \sa lastIndexOf(), contains() */ -/*! \fn template <typename T> qsizetype QList<T>::lastIndexOf(const T &value, qsizetype from = -1) const +/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::lastIndexOf(const AT &value, qsizetype from = -1) const Returns the index position of the last occurrence of the value \a value in the list, searching backward from index position \a @@ -983,7 +1000,7 @@ \sa indexOf() */ -/*! \fn template <typename T> bool QList<T>::contains(const T &value) const +/*! \fn template <typename T> template <typename AT = T> bool QList<T>::contains(const AT &value) const Returns \c true if the list contains an occurrence of \a value; otherwise returns \c false. @@ -994,7 +1011,7 @@ \sa indexOf(), count() */ -/*! \fn template <typename T> bool QList<T>::startsWith(const T &value) const +/*! \fn template <typename T> bool QList<T>::startsWith(parameter_type value) const \since 4.5 Returns \c true if this list is not empty and its first @@ -1003,7 +1020,7 @@ \sa isEmpty(), first() */ -/*! \fn template <typename T> bool QList<T>::endsWith(const T &value) const +/*! \fn template <typename T> bool QList<T>::endsWith(parameter_type value) const \since 4.5 Returns \c true if this list is not empty and its last @@ -1013,7 +1030,7 @@ */ -/*! \fn template <typename T> qsizetype QList<T>::count(const T &value) const +/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::count(const AT &value) const Returns the number of occurrences of \a value in the list. @@ -1051,8 +1068,8 @@ /*! \fn template <typename T> QList<T>::const_iterator QList<T>::cbegin() const \since 5.0 - Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item - in the list. + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the + first item in the list. \include qlist.qdoc iterator-invalidation-func-desc @@ -1061,8 +1078,8 @@ /*! \fn template <typename T> QList<T>::const_iterator QList<T>::constBegin() const - Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item - in the list. + Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the + first item in the list. \include qlist.qdoc iterator-invalidation-func-desc @@ -1071,8 +1088,8 @@ /*! \fn template <typename T> QList<T>::iterator QList<T>::end() - Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item - after the last item in the list. + Returns an \l{STL-style iterators}{STL-style iterator} pointing just after + the last item in the list. \include qlist.qdoc iterator-invalidation-func-desc @@ -1087,8 +1104,8 @@ /*! \fn template <typename T> QList<T>::const_iterator QList<T>::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 list. + Returns a const \l{STL-style iterators}{STL-style iterator} pointing just + after the last item in the list. \include qlist.qdoc iterator-invalidation-func-desc @@ -1097,8 +1114,8 @@ /*! \fn template <typename T> QList<T>::const_iterator QList<T>::constEnd() const - Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary - item after the last item in the list. + Returns a const \l{STL-style iterators}{STL-style iterator} pointing just + after the last item in the list. \include qlist.qdoc iterator-invalidation-func-desc @@ -1108,8 +1125,8 @@ /*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rbegin() \since 5.6 - Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first - item in the list, in reverse order. + Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to + the first item in the list, in reverse order. \include qlist.qdoc iterator-invalidation-func-desc @@ -1124,8 +1141,8 @@ /*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crbegin() const \since 5.6 - Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first - item in the list, in reverse order. + Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing + to the first item in the list, in reverse order. \include qlist.qdoc iterator-invalidation-func-desc @@ -1135,8 +1152,8 @@ /*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rend() \since 5.6 - Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past - the last item in the list, in reverse order. + Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing just + after the last item in the list, in reverse order. \include qlist.qdoc iterator-invalidation-func-desc @@ -1151,8 +1168,8 @@ /*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::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 list, in reverse order. + Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing + just after the last item in the list, in reverse order. \include qlist.qdoc iterator-invalidation-func-desc @@ -1165,6 +1182,7 @@ list, and returns an iterator to the next item in the list (which may be end()). + \include qlist.qdoc shrinking-erase \include qlist.qdoc iterator-invalidation-erase \sa insert(), remove() @@ -1178,6 +1196,7 @@ end. Returns an iterator to the same item that \a end referred to before the call. + \include qlist.qdoc shrinking-erase \include qlist.qdoc iterator-invalidation-erase */ @@ -1236,14 +1255,14 @@ \sa at(), operator[]() */ -/*! \fn template <typename T> T QList<T>::value(qsizetype i, const T &defaultValue) const +/*! \fn template <typename T> T QList<T>::value(qsizetype i, parameter_type defaultValue) const \overload If the index \a i is out of bounds, the function returns \a defaultValue. */ -/*! \fn template <typename T> void QList<T>::push_back(const T &value) +/*! \fn template <typename T> void QList<T>::push_back(parameter_type value) This function is provided for STL compatibility. It is equivalent to append(\a value). @@ -1255,7 +1274,7 @@ */ /*! - \fn template <typename T> void QList<T>::push_front(const T &value) + \fn template <typename T> void QList<T>::push_front(parameter_type value) \fn template <typename T> void QList<T>::push_front(rvalue_ref value) This function is provided for STL compatibility. It is equivalent @@ -1310,6 +1329,15 @@ returns \c false. */ +/*! \fn template <typename T> qsizetype QList<T>::max_size() + \since 6.8 + + This function is provided for STL compatibility. + It returns the maximum number of elements that the list can + theoretically hold. In practice, the number can be much smaller, + limited by the amount of memory available to the system. +*/ + /*! \fn template <typename T> QList<T> &QList<T>::operator+=(const QList<T> &other) Appends the items of the \a other list to this list and @@ -1326,7 +1354,7 @@ \sa operator+(), append() */ -/*! \fn template <typename T> void QList<T>::operator+=(const T &value) +/*! \fn template <typename T> void QList<T>::operator+=(parameter_type value) \overload @@ -1343,7 +1371,11 @@ \sa append(), operator<<() */ -/*! \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const +/*! + \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const & + \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) && + \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) const & + \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) && Returns a list that contains all the items in this list followed by all the items in the \a other list. @@ -1351,15 +1383,7 @@ \sa operator+=() */ -/*! \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) const - \since 6.0 - - \overload - - \sa operator+=() -*/ - -/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const T &value) +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(parameter_type value) Appends \a value to the list and returns a reference to this list. @@ -1386,10 +1410,9 @@ \overload */ -/*! \typedef QList::iterator - - The QList::iterator typedef provides an STL-style non-const - iterator for QList and QStack. +/*! \class QList::iterator + \inmodule QtCore + \brief Provides an STL-style non-const iterator for QList and QStack. QList provides both \l{STL-style iterators} and \l{Java-style iterators}. @@ -1408,10 +1431,9 @@ \sa QList::begin(), QList::end(), QList::const_iterator, QMutableListIterator */ -/*! \typedef QList::const_iterator - - The QList::const_iterator typedef provides an STL-style const - iterator for QList and QStack. +/*! \class QList::const_iterator + \inmodule QtCore + \brief Provides an STL-style const iterator for QList and QStack. QList provides both \l{STL-style iterators} and \l{Java-style iterators}. @@ -1498,7 +1520,7 @@ /*! \fn template <typename T> QList<T> QList<T>::toList() const \fn template <typename T> QList<T> QList<T>::toVector() const - \obsolete + \deprecated A no-op in Qt 6. Provided for backwards compatibility with Qt 5, where QList and QVector where two different types. @@ -1508,7 +1530,7 @@ /*! \fn template <typename T> QList<T> QList<T>::fromList(const QList<T> &list) \fn template <typename T> QList<T> QList<T>::fromVector(const QList<T> &list) - \obsolete + \deprecated A no-op in Qt 6. Provided for backwards compatibility with Qt 5, where QList and QVector were two different types. @@ -1535,3 +1557,73 @@ \sa{Serializing Qt Data Types}{Format of the QDataStream operators} */ + +/*! \fn template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t) + \relates QList + \since 6.1 + + Removes all elements that compare equal to \a t from the + list \a list. Returns the number of elements removed, if any. + + \note Unlike QList::removeAll, \a t is not allowed to be a + reference to an element inside \a list. 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 QList::removeAll(), erase_if +*/ + +/*! \fn template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred) + \relates QList + \since 6.1 + + Removes all elements for which the predicate \a pred returns true + from the list \a list. Returns the number of elements removed, if + any. + + \sa erase +*/ + +/*! \fn template <typename T> QList<T>& QList<T>::assign(qsizetype n, parameter_type t) + \since 6.6 + + Replaces the contents of this list with \a n copies of \a t. + + The size of this list will be equal to \a n. + + This function will only allocate memory if \a n exceeds the capacity of the + list or this list is shared. +*/ + +/*! \fn template <typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator>> QList<T>& QList<T>::assign(InputIterator first, InputIterator last) + \since 6.6 + + Replaces the contents of this list with a copy of the elements in the + iterator range [\a first, \a last). + + The size of this list 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 this list or this list is shared. + + \note This function overload only participates in overload resolution if + \c InputIterator meets the requirements of a + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. + + \note The behavior is undefined if either argument is an iterator into + *this. +*/ + +/*! \fn template <typename T> QList<T>& QList<T>::assign(std::initializer_list<T> l) + \since 6.6 + + Replaces the contents of this list with a copy of the elements of + \a l. + + The size of this list will be equal to the number of elements in + \a l. + + This function only allocates memory if the number of elements in \a l + exceeds the capacity of this list or this list is shared. +*/ |