diff options
Diffstat (limited to 'src/corelib/tools/qlist.qdoc')
| -rw-r--r-- | src/corelib/tools/qlist.qdoc | 339 |
1 files changed, 218 insertions, 121 deletions
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc index 33046f8a2f..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,19 +129,7 @@ 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, iterators are - handy when working with generic algorithms provided by \l{generic - algorithms}{Qt} and the C++ standard library. \l{Java-style iterators} are - provided for backwards compatibility, prefer \l{STL-style iterators} when - writing C++ code. - - \note Iterators and references to individual QList elements are subject to - stability issues. They are often invalidated when QList-modifying operation - (e.g. insert() or remove()) is called. When stability and iterator-like - functionality is required, you should use indexes instead of iterators as - they are not tied to QList internal state and thus do not get invalidated. + 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 @@ -178,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. @@ -283,6 +247,31 @@ \sa resize() */ +/*! \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. @@ -310,11 +299,15 @@ Constructs a list from the std::initializer_list given by \a args. */ -/*! \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. */ @@ -393,7 +386,7 @@ Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically less than} \a other; 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<(). @@ -404,7 +397,7 @@ Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically less than or equal to} \a other; 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<(). @@ -415,7 +408,7 @@ Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically greater than} \a other; 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<(). @@ -426,7 +419,7 @@ Returns \c true if this list is \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} - {lexicographically greater than or equal to} \a other; 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<(). @@ -458,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 @@ -483,28 +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 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. - 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 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 reserve() reserves memory but does not change the size of the list. - Accessing data beyond the end of the list is undefined behavior. + \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() @@ -578,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 @@ -681,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() */ @@ -770,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. @@ -844,6 +859,15 @@ \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() +*/ + /*! \fn template <typename T> qsizetype QList<T>::length() const \since 5.2 @@ -1064,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 @@ -1080,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 @@ -1090,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 @@ -1128,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 @@ -1145,7 +1169,7 @@ \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. + just after the last item in the list, in reverse order. \include qlist.qdoc iterator-invalidation-func-desc @@ -1305,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 @@ -1338,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. @@ -1346,14 +1383,6 @@ \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<<(parameter_type value) Appends \a value to the list and returns a reference to this list. @@ -1381,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}. @@ -1403,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}. @@ -1493,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. @@ -1503,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. @@ -1530,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. +*/ |