diff options
Diffstat (limited to 'src/corelib/tools/qlist.qdoc')
| -rw-r--r-- | src/corelib/tools/qlist.qdoc | 743 |
1 files changed, 451 insertions, 292 deletions
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc index 1a94bf4315..e07b74cd53 100644 --- a/src/corelib/tools/qlist.qdoc +++ b/src/corelib/tools/qlist.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) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \class QVector @@ -124,12 +100,11 @@ many times a particular value occurs in the list, use count(). QList provides these basic functions to add, move, and remove - items: insert(), replace(), remove(), prepend(), append(). With - the exception of append() and replace(), these functions can be slow - (\l{linear time}) for large lists, because they require moving many - items in the list by one position in memory. If you want a container - class that provides fast insertion/removal in the middle, use - std::list instead. + items: insert(), replace(), remove(), prepend(), append(). With the + exception of append(), prepend() and replace(), these functions can be slow + (\l{linear time}) for large lists, because they require moving many items in + the list by one position in memory. If you want a container class that + provides fast insertion/removal in the middle, use std::list instead. Unlike plain C++ arrays, QLists can be resized at any time by calling resize(). If the new size is larger than the old size, @@ -137,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 @@ -154,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 @@ -175,14 +142,16 @@ \section1 Maximum size and out-of-memory conditions - The current version of QList is limited to just under 2 GB (2^31 bytes) - in size. The exact value is architecture-dependent, since it depends on the - overhead required for managing the data block, but is no more than 32 - bytes. The number of elements that can be stored in a QList is that size - divided by the size of each 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. @@ -193,7 +162,7 @@ */ /*! - \fn template <typename T> QList<T> QList<T>::mid(int pos, int length = -1) const + \fn template <typename T> QList<T> QList<T>::mid(qsizetype pos, qsizetype length = -1) const Returns a sub-list which contains elements from this list, starting at position \a pos. If \a length is -1 (the default), all @@ -202,6 +171,55 @@ are included. */ +/*! + \fn template <typename T> QList<T> QList<T>::first(qsizetype n) const + \since 6.0 + + Returns a sub-list that contains the first \a n elements + of this list. + + \note The behavior is undefined when \a n < 0 or \a n > size(). + + \sa last(), sliced() +*/ + +/*! + \fn template <typename T> QList<T> QList<T>::last(qsizetype n) const + \since 6.0 + + Returns a sub-list that contains the last \a n elements of this list. + + \note The behavior is undefined when \a n < 0 or \a n > size(). + + \sa first(), sliced() +*/ + +/*! + \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos, qsizetype n) const + \since 6.0 + + Returns a sub-list that contains \a n elements of this list, + starting at position \a pos. + + \note The behavior is undefined when \a pos < 0, \a n < 0, + or \a pos + \a n > size(). + + \sa first(), last() +*/ + +/*! + \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos) const + \since 6.0 + \overload + + Returns a sub-list that contains the elements of this list starting at + position \a pos and extending to its end. + + \note The behavior is undefined when \a pos < 0 or \a pos > size(). + + \sa first(), last() +*/ + /*! \fn template <typename T> QList<T>::QList() @@ -219,7 +237,7 @@ \since 5.2 */ -/*! \fn template <typename T> QList<T>::QList(int size) +/*! \fn template <typename T> QList<T>::QList(qsizetype size) Constructs a list with an initial size of \a size elements. @@ -229,7 +247,32 @@ \sa resize() */ -/*! \fn template <typename T> QList<T>::QList(int 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. @@ -254,22 +297,18 @@ \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). - The value type of \c InputIterator must be convertible to \c T. -*/ + \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}. -/*! - \fn template <typename T> QList<T>::QList(QArrayDataPointerRef<T> ref) - \internal + The value type of \c InputIterator must be convertible to \c T. */ /*! \fn template <typename T> QList<T>::~QList() @@ -293,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) @@ -309,8 +344,7 @@ never fails. */ -/*! \fn template <typename T> void QList<T>::swapItemsAt(int i, int j) - \since 5.14 +/*! \fn template <typename T> void QList<T>::swapItemsAt(qsizetype i, qsizetype j) Exchange the item at index position \a i with the item at index position \a j. This function assumes that both \a i and \a j are @@ -347,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<(). @@ -406,7 +436,7 @@ This function requires qHash() to be overloaded for the value type \c T. */ -/*! \fn template <typename T> int QList<T>::size() const +/*! \fn template <typename T> qsizetype QList<T>::size() const Returns the number of items in the list. @@ -420,20 +450,37 @@ \sa size(), resize() */ -/*! \fn template <typename T> void QList<T>::resize(int size) +/*! \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> int QList<T>::capacity() const +/*! \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 list without forcing a reallocation. @@ -446,32 +493,35 @@ \note a statically allocated list will report a capacity of 0, even if it's not empty. + \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(int size) +/*! \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() @@ -513,8 +563,8 @@ Example: \snippet code/src_corelib_tools_qlist.cpp 6 - The pointer remains valid as long as the list isn't - reallocated. + \warning The pointer is invalidated on detachment or when the QList is + modified. This function is mostly useful to pass a list to a function that accepts a plain C++ array. @@ -531,8 +581,9 @@ Returns a const pointer to the data stored in the list. The pointer can be used to access the items in the list. - The pointer remains valid as long as the list isn't - reallocated. + + \warning The pointer is invalidated on detachment or when the QList is + modified. This function is mostly useful to pass a list to a function that accepts a plain C++ array. @@ -544,20 +595,17 @@ 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> v ...; - QList<T>().swap(v); - Q_ASSERT(v.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(int i) const +/*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const Returns the item at index position \a i in the list. @@ -567,7 +615,7 @@ \sa value(), operator[]() */ -/*! \fn template <typename T> T &QList<T>::operator[](int i) +/*! \fn template <typename T> T &QList<T>::operator[](qsizetype i) Returns the item at index position \a i as a modifiable reference. @@ -580,7 +628,7 @@ \sa at(), value() */ -/*! \fn template <typename T> const T &QList<T>::operator[](int i) const +/*! \fn template <typename T> const T &QList<T>::operator[](qsizetype i) const \overload @@ -588,7 +636,7 @@ */ /*! - \fn template <typename T> void QList<T>::append(const T &value) + \fn template <typename T> void QList<T>::append(parameter_type value) Inserts \a value at the end of the list. @@ -606,7 +654,7 @@ */ /*! - \fn template <typename T> void QList<T>::append(T &&value) + \fn template <typename T> void QList<T>::append(rvalue_ref value) \since 5.6 \overload @@ -626,10 +674,19 @@ \sa operator<<(), operator+=() */ +/*! \fn template <typename T> void QList<T>::append(QList<T> &&value) + \overload + + \since 6.0 + + Moves the items of the \a value list to the end of this list. + + \sa operator<<(), operator+=() +*/ /*! - \fn template <typename T> void QList<T>::prepend(const T &value) - \fn template <typename T> void QList<T>::prepend(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. @@ -638,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() */ @@ -669,8 +727,8 @@ \sa emplace */ -/*! \fn template <typename T> void QList<T>::insert(int i, const T &value) - \fn template <typename T> void QList<T>::insert(int i, T &&value) +/*! \fn template <typename T> void QList<T>::insert(qsizetype i, parameter_type value) + \fn template <typename T> void QList<T>::insert(qsizetype i, rvalue_ref value) Inserts \a value at index position \a i in the list. If \a i is 0, the value is prepended to the list. If \a i is size(), the @@ -688,7 +746,7 @@ \sa append(), prepend(), remove() */ -/*! \fn template <typename T> void QList<T>::insert(int i, int count, const T &value) +/*! \fn template <typename T> void QList<T>::insert(qsizetype i, qsizetype count, parameter_type value) \overload @@ -699,9 +757,8 @@ \snippet code/src_corelib_tools_qlist.cpp 10 */ -/*! - \fn template <typename T> QList<T>::iterator QList<T>::insert(iterator before, const T &value) - \fn template <typename T> QList<T>::iterator QList<T>::insert(iterator before, T &&value) +/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, parameter_type value) + \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, rvalue_ref value) \overload @@ -709,7 +766,7 @@ \a before. Returns an iterator pointing at the inserted item. */ -/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(iterator before, int count, const T &value) +/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, qsizetype count, parameter_type value) 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 @@ -717,7 +774,7 @@ */ /*! - \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(int i, Args&&... args) + \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(qsizetype i, Args&&... args) Extends the container by inserting a new element at position \a i. This new element is constructed in-place using \a args as the @@ -728,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. @@ -736,7 +793,8 @@ */ -/*! \fn template <typename T> void QList<T>::replace(int 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. @@ -746,26 +804,25 @@ \sa operator[](), remove() */ -/*! \fn template <typename T> void QList<T>::remove(int i) - - \overload - - Removes the element at index position \a i. - - \sa insert(), replace(), fill() -*/ +/*! \fn template <typename T> void QList<T>::remove(qsizetype i, qsizetype n = 1) -/*! \fn template <typename T> void QList<T>::remove(int i, int count) + Removes \a n elements from the list, starting at index position \a i. - \overload +//! [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] - Removes \a count elements from the middle of the list, starting at - index position \a i. +//! [iterator-invalidation-erase] + \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() */ -/*! \fn template <typename T> void QList<T>::removeAt(int i) +/*! \fn template <typename T> void QList<T>::removeAt(qsizetype i) \since 5.2 Removes the element at index position \a i. @@ -774,44 +831,52 @@ remove(i); \endcode - Provided for compatibility with QList. + \include qlist.qdoc shrinking-erase + \include qlist.qdoc iterator-invalidation-erase - \sa remove(), QList::removeAt() + \sa remove() */ -/*! \fn template <typename T> int QList<T>::removeAll(const T &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. - Provided for compatibility with QList. + \include qlist.qdoc shrinking-erase - \sa removeOne(), QList::removeAll() + \sa removeOne() */ -/*! \fn template <typename T> bool QList<T>::removeOne(const T &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. - Provided for compatibility with QList. + \include qlist.qdoc shrinking-erase - \sa removeAll(), QList::removeOne() + \sa removeAll() */ -/*! \fn template <typename T> int QList<T>::length() const +/*! \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() +*/ + +/*! \fn template <typename T> qsizetype QList<T>::length() const \since 5.2 Same as size() and count(). - Provided for compatibility with QList. - - \sa size(), count(), QList::length() + \sa size(), count() */ -/*! \fn template <typename T> T QList<T>::takeAt(int i) +/*! \fn template <typename T> T QList<T>::takeAt(qsizetype i) \since 5.2 Removes the element at index position \a i and returns it. @@ -823,19 +888,15 @@ return t; \endcode - Provided for compatibility with QList. + \include qlist.qdoc iterator-invalidation-erase - \sa takeFirst(), takeLast(), QList::takeAt() + \sa takeFirst(), takeLast() */ -/*! \fn template <typename T> void QList<T>::move(int from, int to) +/*! \fn template <typename T> void QList<T>::move(qsizetype from, qsizetype to) \since 5.6 Moves the item at index position \a from to index position \a to. - - Provided for compatibility with QList. - - \sa QList::move() */ /*! \fn template <typename T> void QList<T>::removeFirst() @@ -845,6 +906,8 @@ the list can be empty, call isEmpty() before calling this function. + \include qlist.qdoc shrinking-erase + \sa remove(), takeFirst(), isEmpty() */ @@ -855,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() */ @@ -882,7 +947,7 @@ */ /*! - \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(QList<T>::iterator before, Args&&... args) + \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(const_iterator before, Args&&... args) \overload @@ -893,11 +958,10 @@ Returns an iterator to the new element. */ -/*! \fn template <typename T> QList<T> &QList<T>::fill(const T &value, int size = -1) +/*! \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 @@ -905,7 +969,7 @@ \sa resize() */ -/*! \fn template <typename T> int QList<T>::indexOf(const T &value, int 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. @@ -920,7 +984,7 @@ \sa lastIndexOf(), contains() */ -/*! \fn template <typename T> int QList<T>::lastIndexOf(const T &value, int 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 @@ -936,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. @@ -947,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 @@ -956,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 @@ -966,7 +1030,7 @@ */ -/*! \fn template <typename T> int 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. @@ -976,7 +1040,7 @@ \sa contains(), indexOf() */ -/*! \fn template <typename T> int QList<T>::count() const +/*! \fn template <typename T> qsizetype QList<T>::count() const \overload @@ -988,6 +1052,11 @@ Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in the list. +//! [iterator-invalidation-func-desc] + \warning The returned iterator is invalidated on detachment or when the + QList is modified. +//! [iterator-invalidation-func-desc] + \sa constBegin(), end() */ @@ -999,24 +1068,30 @@ /*! \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 \sa begin(), cend() */ /*! \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 \sa begin(), constEnd() */ /*! \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 \sa begin(), constEnd() */ @@ -1029,16 +1104,20 @@ /*! \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 \sa cbegin(), end() */ /*! \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 \sa constBegin(), end() */ @@ -1046,8 +1125,10 @@ /*! \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 \sa begin(), crbegin(), rend() */ @@ -1060,8 +1141,10 @@ /*! \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 \sa begin(), rbegin(), rend() */ @@ -1069,8 +1152,10 @@ /*! \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 \sa end(), crend(), rbegin() */ @@ -1083,28 +1168,36 @@ /*! \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 \sa end(), rend(), rbegin() */ -/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(iterator pos) +/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator pos) Removes the item pointed to by the iterator \a pos from the 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() */ -/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(iterator begin, iterator end) +/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator begin, const_iterator end) \overload 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. + + \include qlist.qdoc shrinking-erase + \include qlist.qdoc iterator-invalidation-erase */ /*! \fn template <typename T> T& QList<T>::first() @@ -1151,40 +1244,38 @@ \sa constFirst(), isEmpty(), last() */ -/*! \fn template <typename T> T QList<T>::value(int i) const +/*! \fn template <typename T> T QList<T>::value(qsizetype i) const Returns the value at index position \a i in the list. - 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. + 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 <typename T> T QList<T>::value(int 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. + 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). */ -/*! \fn template <typename T> void QList<T>::push_back(T &&value) +/*! \fn template <typename T> void QList<T>::push_back(rvalue_ref value) \since 5.6 \overload */ /*! - \fn template <typename T> void QList<T>::push_front(const T &value) - \fn template <typename T> void QList<T>::push_front(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 to prepend(\a value). @@ -1238,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 @@ -1246,7 +1346,15 @@ \sa operator+(), append() */ -/*! \fn template <typename T> void QList<T>::operator+=(const T &value) +/*! \fn template <typename T> QList<T> &QList<T>::operator+=(QList<T> &&other) + \since 6.0 + + \overload + + \sa operator+(), append() +*/ + +/*! \fn template <typename T> void QList<T>::operator+=(parameter_type value) \overload @@ -1255,7 +1363,7 @@ \sa append(), operator<<() */ -/*! \fn template <typename T> void QList<T>::operator+=(T &&value) +/*! \fn template <typename T> void QList<T>::operator+=(rvalue_ref value) \since 5.11 \overload @@ -1263,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. @@ -1271,14 +1383,14 @@ \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. \sa append(), operator+=() */ -/*! \fn template <typename T> QList<T> &QList<T>::operator<<(T &&value) +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(rvalue_ref value) \since 5.11 \overload @@ -1292,36 +1404,41 @@ Appends \a other to the list and returns a reference to the list. */ -/*! \typedef QList::iterator +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(QList<T> &&other) + \since 6.0 + + \overload +*/ - 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}. The STL-style non-const iterator is simply a typedef - for "T *" (pointer to T). + iterators}. +//! [iterator-invalidation-class-desc] \warning Iterators on implicitly shared containers do not work exactly like STL-iterators. You should avoid copying a container while iterators are active on that container. For more information, read \l{Implicit sharing iterator problem}. + \warning Iterators are invalidated when QList is modified. Consider that all + iterators are invalidated by default. Exceptions to this rule are explicitly + documented. +//! [iterator-invalidation-class-desc] + \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}. The STL-style const iterator is simply a typedef for - "const T *" (pointer to const T). + iterators}. - \warning Iterators on implicitly shared containers do not work - exactly like STL-iterators. You should avoid copying a container - while iterators are active on that container. For more information, - read \l{Implicit sharing iterator problem}. + \include qlist.qdoc iterator-invalidation-class-desc \sa QList::constBegin(), QList::constEnd(), QList::iterator, QListIterator */ @@ -1332,12 +1449,7 @@ The QList::reverse_iterator typedef provides an STL-style non-const reverse iterator for QList. - It is simply a typedef for \c{std::reverse_iterator<T*>}. - - \warning Iterators on implicitly shared containers do not work - exactly like STL-iterators. You should avoid copying a container - while iterators are active on that container. For more information, - read \l{Implicit sharing iterator problem}. + \include qlist.qdoc iterator-invalidation-class-desc \sa QList::rbegin(), QList::rend(), QList::const_reverse_iterator, QList::iterator */ @@ -1348,12 +1460,7 @@ The QList::const_reverse_iterator typedef provides an STL-style const reverse iterator for QList. - It is simply a typedef for \c{std::reverse_iterator<const T*>}. - - \warning Iterators on implicitly shared containers do not work - exactly like STL-iterators. You should avoid copying a container - while iterators are active on that container. For more information, - read \l{Implicit sharing iterator problem}. + \include qlist.qdoc iterator-invalidation-class-desc \sa QList::rbegin(), QList::rend(), QList::reverse_iterator, QList::const_iterator */ @@ -1370,42 +1477,50 @@ /*! \typedef QList::const_pointer - Typedef for const T *. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::const_reference - Typedef for T &. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::difference_type - Typedef for ptrdiff_t. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::pointer - Typedef for T *. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::reference - Typedef for T &. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::size_type - Typedef for int. Provided for STL compatibility. + Provided for STL compatibility. */ /*! \typedef QList::value_type - Typedef for T. Provided for STL compatibility. + Provided for STL compatibility. +*/ + +/*! \typedef QList::parameter_type + +*/ + +/*! \typedef QList::rvalue_ref + */ /*! \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. @@ -1415,56 +1530,100 @@ /*! \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 where two different types. + Qt 5, where QList and QVector were two different types. Returns this list. */ -/*! \fn template <typename T> QList<T> QList<T>::fromStdVector(const std::vector<T> &vector) +/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list) + \relates QList - Returns a QList object with the data contained in \a vector. The - order of the elements in the QList is the same as in \a vector. + Writes the list \a list to stream \a out. - Example: + This function requires the value type to implement \c operator<<(). - \snippet code/src_corelib_tools_qlist.cpp 16 + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ - \include containers-range-constructor.qdocinc +/*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list) + \relates QList - \sa toStdVector(), QList::fromStdList() -*/ + Reads a list from stream \a in into \a list. -/*! \fn template <typename T> std::vector<T> QList<T>::toStdVector() const + This function requires the value type to implement \c operator>>(). - Returns a std::vector object with the data contained in this QList. - Example: + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ - \snippet code/src_corelib_tools_qlist.cpp 17 +/*! \fn template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t) + \relates QList + \since 6.1 - \include containers-range-constructor.qdocinc + 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 fromStdVector(), QList::toStdList() + \sa QList::removeAll(), erase_if */ -/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list) +/*! \fn template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred) \relates QList + \since 6.1 - Writes the list \a list to stream \a out. + Removes all elements for which the predicate \a pred returns true + from the list \a list. Returns the number of elements removed, if + any. - This function requires the value type to implement \c operator<<(). + \sa erase +*/ - \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +/*! \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> QDataStream &operator>>(QDataStream &in, QList<T> &list) - \relates QList +/*! \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 - Reads a list from stream \a in into \a list. + Replaces the contents of this list with a copy of the elements in the + iterator range [\a first, \a last). - This function requires the value type to implement \c operator>>(). + The size of this list will be equal to the number of elements in the + range [\a first, \a last). - \sa{Serializing Qt Data Types}{Format of the QDataStream operators} + 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. */ |