diff options
Diffstat (limited to 'src/corelib/tools/qlist.qdoc')
| -rw-r--r-- | src/corelib/tools/qlist.qdoc | 1629 |
1 files changed, 1629 insertions, 0 deletions
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc new file mode 100644 index 0000000000..e07b74cd53 --- /dev/null +++ b/src/corelib/tools/qlist.qdoc @@ -0,0 +1,1629 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \class QVector + \inmodule QtCore + \brief QVector is an alias for QList. + + Please see the QList documentation for details. +*/ + +/*! + \class QList + \inmodule QtCore + \brief The QList class is a template class that provides a dynamic array. + + \ingroup tools + \ingroup shared + + \reentrant + + QList\<T\> is one of Qt's generic \l{container classes}. It + stores its items in adjacent memory locations and provides fast + index-based access. QVector\<T\> used to be a different class in + Qt 5, but is now a simple alias to QList. + + QList\<T\> and QVarLengthArray\<T\> + provide similar APIs and functionality. They are often interchangeable, + but there are performance consequences. Here is an overview of use cases: + + \list + \li QList should be your default first choice. + \li QVarLengthArray provides an array that reserves space on the stack, + but can dynamically grow onto the heap if required. It's good to + use for short lived containers that are usually small. + \li If you need a real linked list, which guarantees + \l{Algorithmic Complexity}{constant time} insertions mid-list and + uses iterators to items rather than indexes, use std::list. + \endlist + + \note QList and QVarLengthArray both guarantee C-compatible + array layout. + \note QList in Qt 5 did not always have a C-compatible array layout and + we often recommended to use QVector instead for more predictable + performance. This is not the case in Qt 6 anymore, where both classes + now share an implementation and can be used interchangeably. + + Here's an example of a QList that stores integers and a QList + that stores QString values: + + \snippet code/src_corelib_tools_qlist.cpp 0 + + QList stores its items in an array of continuous memory. Typically, lists + are created with an initial size. For example, the following code + constructs a QList with 200 elements: + + \snippet code/src_corelib_tools_qlist.cpp 1 + + The elements are automatically initialized with a + \l{default-constructed value}. If you want to initialize the + list with a different value, pass that value as the second + argument to the constructor: + + \snippet code/src_corelib_tools_qlist.cpp 2 + + You can also call fill() at any time to fill the list with a + value. + + QList uses 0-based indexes, just like C++ arrays. To access the + item at a particular index position, you can use operator[](). On + non-const lists, operator[]() returns a reference to the item + that can be used on the left side of an assignment: + + \snippet code/src_corelib_tools_qlist.cpp 3 + + For read-only access, an alternative syntax is to use at(): + + \snippet code/src_corelib_tools_qlist.cpp 4 + + at() can be faster than operator[](), because it never causes a + \l{deep copy} to occur. + + Another way to access the data stored in a QList is to call + data(). The function returns a pointer to the first item in the + list. You can use the pointer to directly access and modify the + elements stored in the list. The pointer is also useful if you + need to pass a QList to a function that accepts a plain C++ + array. + + If you want to find all occurrences of a particular value in a + list, use indexOf() or lastIndexOf(). The former searches + forward starting from a given index position, the latter searches + backward. Both return the index of the matching item if they found + one; otherwise, they return -1. For example: + + \snippet code/src_corelib_tools_qlist.cpp 5 + + If you simply want to check whether a list contains a + particular value, use contains(). If you want to find out how + 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(), 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, + QList might need to reallocate the whole list. QList tries + to reduce the number of reallocations by preallocating up to twice + as much memory as the actual data needs. + + 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, 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 + won't let you, for example, store a QWidget as a value; instead, + store a QWidget *. A few functions have additional requirements; + for example, indexOf() and lastIndexOf() expect the value type to + support \c operator==(). These requirements are documented on a + per-function basis. + + 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. + + \section2 More Information on Using Qt Containers + + For a detailed discussion comparing Qt containers with each other and + with STL containers, see \l {Understand the Qt Containers}. + + \section1 Maximum size and out-of-memory conditions + + 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. + + 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. + + Note that the operating system may impose further limits on applications + holding a lot of allocated memory, especially large, contiguous blocks. + Such considerations, the configuration of such behavior or any mitigation + are outside the scope of the Qt API. +*/ + +/*! + \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 + elements after \a pos are included; otherwise \a length elements (or + all remaining elements if there are less than \a length elements) + 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() + + Constructs an empty list. + + \sa resize() +*/ + +/*! + \fn template <typename T> QList<T>::QList(QList<T> &&other) + + Move-constructs a QList instance, making it point at the same + object that \a other was pointing to. + + \since 5.2 +*/ + +/*! \fn template <typename T> QList<T>::QList(qsizetype size) + + Constructs a list with an initial size of \a size elements. + + The elements are initialized with a \l{default-constructed + value}. + + \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. + Each element is initialized with \a value. + + \sa resize(), fill() +*/ + +/*! \fn template <typename T> QList<T>::QList(const QList<T> &other) + + Constructs a copy of \a other. + + This operation takes \l{Algorithmic Complexity}{constant time}, + because QList is \l{implicitly shared}. This makes returning + a QList from a function very fast. If a shared instance is + modified, it will be copied (copy-on-write), and that takes + \l{Algorithmic Complexity}{linear time}. + + \sa operator=() +*/ + +/*! \fn template <typename T> QList<T>::QList(std::initializer_list<T> args) + \since 4.8 + + Constructs a list from the std::initializer_list given by \a args. +*/ + +/*! \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. +*/ + +/*! \fn template <typename T> QList<T>::~QList() + + Destroys the list. +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator=(const QList<T> &other) + + Assigns \a other to this list and returns a reference to this + list. +*/ + +/*! + \fn template <typename T> QList<T> &QList<T>::operator=(QList<T> &&other) + + Move-assigns \a other to this QList instance. + + \since 5.2 +*/ + +/*! + \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. +*/ + +/*! \fn template <typename T> void QList<T>::swap(QList<T> &other) + \since 4.8 + + Swaps list \a other with this list. This operation is very fast and + never fails. +*/ + +/*! \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 + at least 0 but less than size(). To avoid failure, test that both + \a i and \a j are at least 0 and less than size(). +*/ + + +/*! \fn template <typename T> bool QList<T>::operator==(const QList<T> &other) const + + Returns \c true if \a other is equal to this list; otherwise + returns \c false. + + Two lists are considered equal if they contain the same values + in the same order. + + This function requires the value type to have an implementation + of \c operator==(). + + \sa operator!=() +*/ + +/*! \fn template <typename T> bool QList<T>::operator!=(const QList<T> &other) const + + Returns \c true if \a other is not equal to this list; otherwise + returns \c false. + + Two lists are considered equal if they contain the same values + in the same order. + + This function requires the value type to have an implementation + of \c operator==(). + + \sa operator==() +*/ + +/*! \fn template <typename T> bool QList<T>::operator<(const QList<T> &other) const + \since 5.6 + + Returns \c true if this list is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {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 QList<T>::operator<=(const QList<T> &other) const + \since 5.6 + + Returns \c true if this list is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {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 QList<T>::operator>(const QList<T> &other) const + \since 5.6 + + Returns \c true if this list is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {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 QList<T>::operator>=(const QList<T> &other) const + \since 5.6 + + Returns \c true if this list is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {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<(). +*/ + +/*! + \fn template <typename T> size_t qHash(const QList<T> &key, size_t seed = 0) + \since 5.6 + \relates QList + + Returns the hash value for \a key, + using \a seed to seed the calculation. + + This function requires qHash() to be overloaded for the value type \c T. +*/ + +/*! \fn template <typename T> qsizetype QList<T>::size() const + + Returns the number of items in the list. + + \sa isEmpty(), resize() +*/ + +/*! \fn template <typename T> bool QList<T>::isEmpty() const + + Returns \c true if the list has size 0; otherwise returns \c false. + + \sa size(), resize() +*/ + +/*! \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 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. + + \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 + list without forcing a reallocation. + + The sole purpose of this function is to provide a means of fine + tuning QList's memory usage. In general, you will rarely ever + need to call this function. If you want to know how many items are + in the list, call size(). + + \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(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. If you resize + the list often, you are also likely to get better performance. + + 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 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(), resize() +*/ + +/*! \fn template <typename T> void QList<T>::squeeze() + + Releases any memory not required to store the items. + + The sole purpose of this function is to provide a means of fine + tuning QList's memory usage. In general, you will rarely ever + need to call this function. + + \sa reserve(), capacity() +*/ + +/*! \fn template <typename T> void QList<T>::detach() + + \internal +*/ + +/*! \fn template <typename T> bool QList<T>::isDetached() const + + \internal +*/ + +/*! \fn template <typename T> void QList<T>::setSharable(bool sharable) + + \internal +*/ + +/*! \fn template <typename T> bool QList<T>::isSharedWith(const QList<T> &other) const + + \internal +*/ + +/*! \fn template <typename T> T *QList<T>::data() + + Returns a pointer to the data stored in the list. The pointer + can be used to access and modify the items in the list. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 6 + + \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. + + \sa constData(), operator[]() +*/ + +/*! \fn template <typename T> const T *QList<T>::data() const + + \overload +*/ + +/*! \fn template <typename T> const T *QList<T>::constData() const + + Returns a const pointer to the data stored in the list. The + pointer can be used to access the items in the list. + + \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. + + \sa data(), operator[]() +*/ + +/*! \fn template <typename T> void QList<T>::clear() + + Removes all the elements from the list. + + 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 resize(), squeeze() +*/ + +/*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const + + Returns the item at index position \a i in the list. + + \a i must be a valid index position in the list (i.e., 0 <= \a + i < size()). + + \sa value(), operator[]() +*/ + +/*! \fn template <typename T> T &QList<T>::operator[](qsizetype i) + + Returns the item at index position \a i as a modifiable reference. + + \a i must be a valid index position in the list (i.e., 0 <= \a i + < size()). + + Note that using non-const operators can cause QList to do a deep + copy. + + \sa at(), value() +*/ + +/*! \fn template <typename T> const T &QList<T>::operator[](qsizetype i) const + + \overload + + Same as at(\a i). +*/ + +/*! + \fn template <typename T> void QList<T>::append(parameter_type value) + + Inserts \a value at the end of the list. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 7 + + This is the same as calling resize(size() + 1) and assigning \a + value to the new last element in the list. + + This operation is relatively fast, because QList typically + allocates more memory than necessary, so it can grow without + reallocating the entire list each time. + + \sa operator<<(), prepend(), insert() +*/ + +/*! + \fn template <typename T> void QList<T>::append(rvalue_ref value) + \since 5.6 + + \overload + + Example: + \snippet code/src_corelib_tools_qlist.cpp move-append +*/ + +/*! \fn template <typename T> void QList<T>::append(const QList<T> &value) + + \overload + + \since 5.5 + + Appends the items of the \a value list to this list. + + \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(parameter_type value) + \fn template <typename T> void QList<T>::prepend(rvalue_ref value) + + Inserts \a value at the beginning of the list. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 8 + + This is the same as list.insert(0, \a value). + + 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() +*/ + +/*! + \fn template <typename T> template <typename ...Args> T &QList<T>::emplaceBack(Args&&... args) + \fn template <typename T> template <typename ...Args> T &QList<T>::emplace_back(Args&&... args) + + Adds a new element to the end for the container. This new element + is constructed in-place using \a args as the arguments for its + construction. + + Returns a reference to the new element. + + Example: + \snippet code/src_corelib_tools_qlist.cpp emplace-back + + It is also possible to access a newly created object by using + returned reference: + \snippet code/src_corelib_tools_qlist.cpp emplace-back-ref + + This is the same as list.emplace(list.size(), \a args). + + \sa emplace +*/ + +/*! \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 + value is appended to the list. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 9 + + For large lists, this operation can be slow (\l{linear time}), + because it requires moving all the items at indexes \a i and + above by one position further in memory. If you want a container + class that provides a fast insert() function, use std::list + instead. + + \sa append(), prepend(), remove() +*/ + +/*! \fn template <typename T> void QList<T>::insert(qsizetype i, qsizetype count, parameter_type value) + + \overload + + Inserts \a count copies of \a value at index position \a i in the + list. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 10 +*/ + +/*! \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 + + Inserts \a value in front of the item pointed to by the iterator + \a before. Returns an iterator pointing at the inserted item. +*/ + +/*! \fn template <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 + first of the inserted items. +*/ + +/*! + \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 + arguments for its construction. + + Returns an iterator to the new element. + + Example: + \snippet code/src_corelib_tools_qlist.cpp emplace + + \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. + + \sa emplaceBack +*/ + + +/*! \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. + + \a i must be a valid index position in the list (i.e., 0 <= \a + i < size()). + + \sa operator[](), remove() +*/ + +/*! \fn template <typename T> void QList<T>::remove(qsizetype i, qsizetype n = 1) + + Removes \a n elements from the list, starting at index position \a i. + +//! [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}, 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(qsizetype i) + \since 5.2 + + Removes the element at index position \a i. + Equivalent to + \code + remove(i); + \endcode + + \include qlist.qdoc shrinking-erase + \include qlist.qdoc iterator-invalidation-erase + + \sa remove() +*/ + +/*! \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 = 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() +*/ + +/*! \fn template <typename T> qsizetype QList<T>::length() const + \since 5.2 + + Same as size() and count(). + + \sa size(), count() +*/ + +/*! \fn template <typename T> T QList<T>::takeAt(qsizetype i) + \since 5.2 + + Removes the element at index position \a i and returns it. + + Equivalent to + \code + T t = at(i); + remove(i); + return t; + \endcode + + \include qlist.qdoc iterator-invalidation-erase + + \sa takeFirst(), takeLast() +*/ + +/*! \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. +*/ + +/*! \fn template <typename T> void QList<T>::removeFirst() + \since 5.1 + Removes the first item in the list. Calling this function is + equivalent to calling remove(0). The list must not be empty. If + the list can be empty, call isEmpty() before calling this + function. + + \include qlist.qdoc shrinking-erase + + \sa remove(), takeFirst(), isEmpty() +*/ + +/*! \fn template <typename T> void QList<T>::removeLast() + \since 5.1 + Removes the last item in the list. Calling this function is + equivalent to calling remove(size() - 1). The list must not be + empty. If the list can be empty, call isEmpty() before calling + this function. + + \include qlist.qdoc shrinking-erase + + \sa remove(), takeLast(), removeFirst(), isEmpty() +*/ + +/*! \fn template <typename T> T QList<T>::takeFirst() + \since 5.1 + + Removes the first item in the list and returns it. This function + assumes the list is not empty. To avoid failure, call isEmpty() + before calling this function. + + \sa takeLast(), removeFirst() +*/ + +/*! \fn template <typename T> T QList<T>::takeLast() + \since 5.1 + + Removes the last item in the list and returns it. This function + assumes the list is not empty. To avoid failure, call isEmpty() + before calling this function. + + If you don't use the return value, removeLast() is more + efficient. + + \sa takeFirst(), removeLast() +*/ + +/*! + \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(const_iterator before, Args&&... args) + + \overload + + Creates a new element in front of the item pointed to by the + iterator \a before. This new element is constructed in-place + using \a args as the arguments for its construction. + + Returns an iterator to the new element. +*/ + +/*! \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 \a size beforehand. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 11 + + \sa resize() +*/ + +/*! \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. + Returns -1 if no item matched. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 12 + + This function requires the value type to have an implementation of + \c operator==(). + + \sa lastIndexOf(), contains() +*/ + +/*! \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 + from. If \a from is -1 (the default), the search starts at the + last item. Returns -1 if no item matched. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 13 + + This function requires the value type to have an implementation of + \c operator==(). + + \sa indexOf() +*/ + +/*! \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. + + This function requires the value type to have an implementation of + \c operator==(). + + \sa indexOf(), count() +*/ + +/*! \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 + item is equal to \a value; otherwise returns \c false. + + \sa isEmpty(), first() +*/ + +/*! \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 + item is equal to \a value; otherwise returns \c false. + + \sa isEmpty(), last() +*/ + + +/*! \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. + + This function requires the value type to have an implementation of + \c operator==(). + + \sa contains(), indexOf() +*/ + +/*! \fn template <typename T> qsizetype QList<T>::count() const + + \overload + + Same as size(). +*/ + +/*! \fn template <typename T> QList<T>::iterator QList<T>::begin() + + 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() +*/ + +/*! \fn template <typename T> QList<T>::const_iterator QList<T>::begin() const + + \overload +*/ + +/*! \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. + + \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. + + \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 just after + the last item in the list. + + \include qlist.qdoc iterator-invalidation-func-desc + + \sa begin(), constEnd() +*/ + +/*! \fn template <typename T> QList<T>::const_iterator QList<T>::end() const + + \overload +*/ + +/*! \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 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 just + after the last item in the list. + + \include qlist.qdoc iterator-invalidation-func-desc + + \sa constBegin(), end() +*/ + +/*! \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. + + \include qlist.qdoc iterator-invalidation-func-desc + + \sa begin(), crbegin(), rend() +*/ + +/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rbegin() const + \since 5.6 + \overload +*/ + +/*! \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. + + \include qlist.qdoc iterator-invalidation-func-desc + + \sa begin(), rbegin(), rend() +*/ + +/*! \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 just + after the last item in the list, in reverse order. + + \include qlist.qdoc iterator-invalidation-func-desc + + \sa end(), crend(), rbegin() +*/ + +/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rend() const + \since 5.6 + \overload +*/ + +/*! \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 + 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(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(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() + + Returns a reference to the first item in the list. This + function assumes that the list isn't empty. + + \sa last(), isEmpty(), constFirst() +*/ + +/*! \fn template <typename T> const T& QList<T>::first() const + + \overload +*/ + +/*! \fn template <typename T> const T& QList<T>::constFirst() const + \since 5.6 + + Returns a const reference to the first item in the list. This + function assumes that the list isn't empty. + + \sa constLast(), isEmpty(), first() +*/ + +/*! \fn template <typename T> T& QList<T>::last() + + Returns a reference to the last item in the list. This function + assumes that the list isn't empty. + + \sa first(), isEmpty(), constLast() +*/ + +/*! \fn template <typename T> const T& QList<T>::last() const + + \overload +*/ + +/*! \fn template <typename T> const T& QList<T>::constLast() const + \since 5.6 + + Returns a const reference to the last item in the list. This function + assumes that the list isn't empty. + + \sa constFirst(), isEmpty(), last() +*/ + +/*! \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. + + \sa at(), operator[]() +*/ + +/*! \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(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(rvalue_ref value) + \since 5.6 + \overload +*/ + +/*! + \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). +*/ + +/*! \fn template <typename T> void QList<T>::pop_front() + + This function is provided for STL compatibility. It is equivalent + to removeFirst(). +*/ + +/*! \fn template <typename T> void QList<T>::pop_back() + + This function is provided for STL compatibility. It is equivalent + to removeLast(). +*/ + +/*! \fn template <typename T> T& QList<T>::front() + + This function is provided for STL compatibility. It is equivalent + to first(). +*/ + +/*! \fn template <typename T> QList<T>::const_reference QList<T>::front() const + + \overload +*/ + +/*! \fn template <typename T> QList<T>::reference QList<T>::back() + + This function is provided for STL compatibility. It is equivalent + to last(). +*/ + +/*! \fn template <typename T> QList<T>::const_reference QList<T>::back() const + + \overload +*/ + +/*! \fn template <typename T> void QList<T>::shrink_to_fit() + \since 5.10 + + This function is provided for STL compatibility. It is equivalent + to squeeze(). +*/ + +/*! \fn template <typename T> bool QList<T>::empty() const + + This function is provided for STL compatibility. It is equivalent + to isEmpty(), returning \c true if the list is empty; otherwise + 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 + returns a reference to this list. + + \sa operator+(), append() +*/ + +/*! \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 + + Appends \a value to the list. + + \sa append(), operator<<() +*/ + +/*! \fn template <typename T> void QList<T>::operator+=(rvalue_ref value) + \since 5.11 + + \overload + + \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) && + \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. + + \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. + + \sa append(), operator+=() +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(rvalue_ref value) + \since 5.11 + + \overload + + \sa append(), operator+=() +*/ + + +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const QList<T> &other) + + Appends \a other to the list and returns a reference to the list. +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(QList<T> &&other) + \since 6.0 + + \overload +*/ + +/*! \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}. + +//! [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 +*/ + +/*! \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}. + + \include qlist.qdoc iterator-invalidation-class-desc + + \sa QList::constBegin(), QList::constEnd(), QList::iterator, QListIterator +*/ + +/*! \typedef QList::reverse_iterator + \since 5.6 + + The QList::reverse_iterator typedef provides an STL-style non-const + reverse iterator for QList. + + \include qlist.qdoc iterator-invalidation-class-desc + + \sa QList::rbegin(), QList::rend(), QList::const_reverse_iterator, QList::iterator +*/ + +/*! \typedef QList::const_reverse_iterator + \since 5.6 + + The QList::const_reverse_iterator typedef provides an STL-style const + reverse iterator for QList. + + \include qlist.qdoc iterator-invalidation-class-desc + + \sa QList::rbegin(), QList::rend(), QList::reverse_iterator, QList::const_iterator +*/ + +/*! \typedef QList::Iterator + + Qt-style synonym for QList::iterator. +*/ + +/*! \typedef QList::ConstIterator + + Qt-style synonym for QList::const_iterator. +*/ + +/*! \typedef QList::const_pointer + + Provided for STL compatibility. +*/ + +/*! \typedef QList::const_reference + + Provided for STL compatibility. +*/ + +/*! \typedef QList::difference_type + + Provided for STL compatibility. +*/ + +/*! \typedef QList::pointer + + Provided for STL compatibility. +*/ + +/*! \typedef QList::reference + + Provided for STL compatibility. +*/ + +/*! \typedef QList::size_type + + Provided for STL compatibility. +*/ + +/*! \typedef QList::value_type + + 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 + \deprecated + + A no-op in Qt 6. Provided for backwards compatibility with + Qt 5, where QList and QVector where two different types. + + Returns this list. +*/ + +/*! \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) + \deprecated + + A no-op in Qt 6. Provided for backwards compatibility with + Qt 5, where QList and QVector were two different types. + + Returns this list. +*/ + +/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list) + \relates QList + + Writes the list \a list to stream \a out. + + This function requires the value type to implement \c operator<<(). + + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ + +/*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list) + \relates QList + + Reads a list from stream \a in into \a list. + + This function requires the value type to implement \c operator>>(). + + \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. +*/ |