diff options
Diffstat (limited to 'src/corelib/tools/qlist.qdoc')
| -rw-r--r-- | src/corelib/tools/qlist.qdoc | 1472 |
1 files changed, 1472 insertions, 0 deletions
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc new file mode 100644 index 0000000000..c0af194858 --- /dev/null +++ b/src/corelib/tools/qlist.qdoc @@ -0,0 +1,1472 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \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 a vector (array). Typically, vectors + 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 + vector 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 vector 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 vectors, 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 + vector. You can use the pointer to directly access and modify the + elements stored in the vector. 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 + vector, 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 vector contains a + particular value, use contains(). If you want to find out how + many times a particular value occurs in the vector, 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 vectors, because they require moving many + items in the vector 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 vector. QList tries + 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. + + 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}. + + 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. + + Like the other container classes, QList provides \l{Java-style + iterators} (QListIterator and QMutableVectorIterator) 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. + + 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 + with STL containers, see \l {Understand the Qt Containers}. + + \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. + + 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 + 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(int pos, int length = -1) const + + Returns a sub-vector which contains elements from this vector, + 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() + + Constructs an empty vector. + + \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(int size) + + Constructs a vector 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(int size, const T &value) + + Constructs a vector 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 vector 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) + \since 5.14 + + Constructs a vector with the contents in the iterator range [\a first, \a last). + + The value type of \c InputIterator must be convertible to \c T. +*/ + +/*! + \fn template <typename T> QList<T>::QList(QArrayDataPointerRef<T> ref) + \internal +*/ + +/*! \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 vector and returns a reference to this + vector. +*/ + +/*! + \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) + + 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) + \since 4.8 + + Swaps vector \a other with this vector. This operation is very fast and + never fails. +*/ + +/*! \fn template <typename T> void QList<T>::swapItemsAt(int i, int j) + \since 5.14 + + 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 vector; otherwise + returns \c false. + + Two vectors 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 vector; otherwise + returns \c false. + + Two vectors 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 operator<(const QList<T> &lhs, const QList<T> &rhs) + \since 5.6 + \relates QList + + Returns \c true if vector \a lhs is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {lexicographically less than} \a rhs; 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) + \since 5.6 + \relates QList + + Returns \c true if vector \a lhs is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {lexicographically less than or equal to} \a rhs; 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) + \since 5.6 + \relates QList + + Returns \c true if vector \a lhs is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {lexicographically greater than} \a rhs; 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) + \since 5.6 + \relates QList + + Returns \c true if vector \a lhs is + \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare} + {lexicographically greater than or equal to} \a rhs; 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> int QList<T>::size() const + + Returns the number of items in the vector. + + \sa isEmpty(), resize() +*/ + +/*! \fn template <typename T> bool QList<T>::isEmpty() const + + Returns \c true if the vector has size 0; otherwise returns \c false. + + \sa size(), resize() +*/ + +/*! \fn template <typename T> void QList<T>::resize(int size) + + Sets the size of the vector 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. + + Since Qt 5.6, resize() doesn't shrink the capacity anymore. + To shed excess capacity, use squeeze(). + + \sa size() +*/ + +/*! \fn template <typename T> int QList<T>::capacity() const + + Returns the maximum number of items that can be stored in the + vector 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 vector, call size(). + + \note a statically allocated vector will report a capacity of 0, + even if it's not empty. + + \sa reserve(), squeeze() +*/ + +/*! \fn template <typename T> void QList<T>::reserve(int size) + + Attempts to allocate memory for at least \a size elements. If you + know in advance how large the vector will be, you should call this + function to prevent reallocations and memory fragmentation. + + 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. + + 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(). + + \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. + + \sa squeeze(), capacity() +*/ + +/*! \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 vector. The pointer + can be used to access and modify the items in the vector. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 6 + + The pointer remains valid as long as the vector isn't + reallocated. + + This function is mostly useful to pass a vector 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 vector. The + pointer can be used to access the items in the vector. + The pointer remains valid as long as the vector isn't + reallocated. + + This function is mostly useful to pass a vector 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 vector. + + \note Until Qt 5.6, this also released the memory used by + the vector. From Qt 5.7, the capacity is preserved. To shed + all capacity, swap with a default-constructed vector: + \code + QList<T> v ...; + QList<T>().swap(v); + Q_ASSERT(v.capacity() == 0); + \endcode + or call squeeze(). + + \sa squeeze() +*/ + +/*! \fn template <typename T> const T &QList<T>::at(int i) const + + Returns the item at index position \a i in the vector. + + \a i must be a valid index position in the vector (i.e., 0 <= \a + i < size()). + + \sa value(), operator[]() +*/ + +/*! \fn template <typename T> T &QList<T>::operator[](int i) + + Returns the item at index position \a i as a modifiable reference. + + \a i must be a valid index position in the vector (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[](int i) const + + \overload + + Same as at(\a i). +*/ + +/*! + \fn template <typename T> void QList<T>::append(const T &value) + + Inserts \a value at the end of the vector. + + 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 vector. + + This operation is relatively fast, because QList typically + allocates more memory than necessary, so it can grow without + reallocating the entire vector each time. + + \sa operator<<(), prepend(), insert() +*/ + +/*! + \fn template <typename T> void QList<T>::append(T &&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 vector to this vector. + + \sa operator<<(), operator+=() +*/ + + +/*! + \fn template <typename T> void QList<T>::prepend(const T &value) + \fn template <typename T> void QList<T>::prepend(T &&value) + + Inserts \a value at the beginning of the vector. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 8 + + This is the same as vector.insert(0, \a value). + + For large vectors, this operation can be slow (\l{linear time}), + because it requires moving all the items in the vector by one + position further in memory. If you want a container class that + provides a fast prepend operation, use std::list + instead. + + \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 vector.emplace(vector.size(), \a args). + + \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) + + Inserts \a value at index position \a i in the vector. If \a i is + 0, the value is prepended to the vector. If \a i is size(), the + value is appended to the vector. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 9 + + For large vectors, 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(int i, int count, const T &value) + + \overload + + Inserts \a count copies of \a value at index position \a i in the + vector. + + Example: + \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) + + \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(iterator before, int count, const T &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(int 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 garanteed 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(int i, const T &value) + + Replaces the item at index position \a i with \a value. + + \a i must be a valid index position in the vector (i.e., 0 <= \a + i < size()). + + \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(int i, int count) + + \overload + + Removes \a count elements from the middle of the vector, starting at + index position \a i. + + \sa insert(), replace(), fill() +*/ + +/*! \fn template <typename T> void QList<T>::removeAt(int i) + \since 5.2 + + Removes the element at index position \a i. + Equivalent to + \code + remove(i); + \endcode + + Provided for compatibility with QList. + + \sa remove(), QList::removeAt() +*/ + +/*! \fn template <typename T> int QList<T>::removeAll(const T &t) + \since 5.4 + + Removes all elements that compare equal to \a t from the + vector. Returns the number of elements removed, if any. + + Provided for compatibility with QList. + + \sa removeOne(), QList::removeAll() +*/ + +/*! \fn template <typename T> bool QList<T>::removeOne(const T &t) + \since 5.4 + + Removes the first element that compares equal to \a t from the + vector. Returns whether an element was, in fact, removed. + + Provided for compatibility with QList. + + \sa removeAll(), QList::removeOne() +*/ + +/*! \fn template <typename T> int QList<T>::length() const + \since 5.2 + + Same as size() and count(). + + Provided for compatibility with QList. + + \sa size(), count(), QList::length() +*/ + +/*! \fn template <typename T> T QList<T>::takeAt(int 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 + + Provided for compatibility with QList. + + \sa takeFirst(), takeLast(), QList::takeAt() +*/ + +/*! \fn template <typename T> void QList<T>::move(int from, int 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() + \since 5.1 + Removes the first item in the vector. Calling this function is + equivalent to calling remove(0). The vector must not be empty. If + the vector can be empty, call isEmpty() before calling this + function. + + \sa remove(), takeFirst(), isEmpty() +*/ + +/*! \fn template <typename T> void QList<T>::removeLast() + \since 5.1 + Removes the last item in the vector. Calling this function is + equivalent to calling remove(size() - 1). The vector must not be + empty. If the vector can be empty, call isEmpty() before calling + this function. + + \sa remove(), takeLast(), removeFirst(), isEmpty() +*/ + +/*! \fn template <typename T> T QList<T>::takeFirst() + \since 5.1 + + Removes the first item in the vector and returns it. This function + assumes the vector 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 vector 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(QList<T>::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(const T &value, int size = -1) + + Assigns \a value to all items in the vector. If \a size is + different from -1 (the default), the vector is resized to size \a + size beforehand. + + Example: + \snippet code/src_corelib_tools_qlist.cpp 11 + + \sa resize() +*/ + +/*! \fn template <typename T> int QList<T>::indexOf(const T &value, int from = 0) const + + Returns the index position of the first occurrence of \a value in + the vector, 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> int QList<T>::lastIndexOf(const T &value, int from = -1) const + + Returns the index position of the last occurrence of the value \a + value in the vector, 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> bool QList<T>::contains(const T &value) const + + Returns \c true if the vector 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(const T &value) const + \since 4.5 + + Returns \c true if this vector 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(const T &value) const + \since 4.5 + + Returns \c true if this vector is not empty and its last + item is equal to \a value; otherwise returns \c false. + + \sa isEmpty(), last() +*/ + + +/*! \fn template <typename T> int QList<T>::count(const T &value) const + + Returns the number of occurrences of \a value in the vector. + + This function requires the value type to have an implementation of + \c operator==(). + + \sa contains(), indexOf() +*/ + +/*! \fn template <typename T> int 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 vector. + + \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 vector. + + \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 vector. + + \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 vector. + + \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 to the imaginary + item after the last item in the vector. + + \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 vector. + + \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 vector, in reverse order. + + \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 vector, in reverse order. + + \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 to one past + the last item in the vector, in reverse order. + + \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 to one + past the last item in the vector, in reverse order. + + \sa end(), rend(), rbegin() +*/ + +/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(iterator pos) + + Removes the item pointed to by the iterator \a pos from the + vector, and returns an iterator to the next item in the vector + (which may be end()). + + \sa insert(), remove() +*/ + +/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(iterator begin, 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. +*/ + +/*! \fn template <typename T> T& QList<T>::first() + + Returns a reference to the first item in the vector. This + function assumes that the vector 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 vector. This + function assumes that the vector isn't empty. + + \sa constLast(), isEmpty(), first() +*/ + +/*! \fn template <typename T> T& QList<T>::last() + + Returns a reference to the last item in the vector. This function + assumes that the vector 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 vector. This function + assumes that the vector isn't empty. + + \sa constFirst(), isEmpty(), last() +*/ + +/*! \fn template <typename T> T QList<T>::value(int i) const + + Returns the value at index position \a i in the vector. + + 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 + + \overload + + If the index \a i is out of bounds, the function returns + \a defaultValue. +*/ + +/*! \fn template <typename T> void QList<T>::push_back(const T &value) + + 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) + \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) + + 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 vector is empty; otherwise + returns \c false. +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator+=(const QList<T> &other) + + Appends the items of the \a other vector to this vector and + returns a reference to this vector. + + \sa operator+(), append() +*/ + +/*! \fn template <typename T> void QList<T>::operator+=(const T &value) + + \overload + + Appends \a value to the vector. + + \sa append(), operator<<() +*/ + +/*! \fn template <typename T> void QList<T>::operator+=(T &&value) + \since 5.11 + + \overload + + \sa append(), operator<<() +*/ + +/*! \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const + + Returns a vector that contains all the items in this vector + followed by all the items in the \a other vector. + + \sa operator+=() +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const T &value) + + Appends \a value to the vector and returns a reference to this + vector. + + \sa append(), operator+=() +*/ + +/*! \fn template <typename T> QList<T> &QList<T>::operator<<(T &&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 vector and returns a reference to the + vector. +*/ + +/*! \typedef QList::iterator + + The QList::iterator typedef 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). + + \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}. + + \sa QList::begin(), QList::end(), QList::const_iterator, QMutableVectorIterator +*/ + +/*! \typedef QList::const_iterator + + The QList::const_iterator typedef 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). + + \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}. + + \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. + + 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}. + + \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. + + 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}. + + \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 + + Typedef for const T *. Provided for STL compatibility. +*/ + +/*! \typedef QList::const_reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! \typedef QList::difference_type + + Typedef for ptrdiff_t. Provided for STL compatibility. +*/ + +/*! \typedef QList::pointer + + Typedef for T *. Provided for STL compatibility. +*/ + +/*! \typedef QList::reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! \typedef QList::size_type + + Typedef for int. Provided for STL compatibility. +*/ + +/*! \typedef QList::value_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! \fn template <typename T> QList<T> QList<T>::toList() const + \fn template <typename T> QList<T> QList<T>::toVector() const + \obsolete + + 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) + \obsolete + + 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>::fromStdVector(const std::vector<T> &vector) + + 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. + + Example: + + \snippet code/src_corelib_tools_qlist.cpp 16 + + \include containers-range-constructor.qdocinc + + \sa toStdVector(), QList::fromStdList() +*/ + +/*! \fn template <typename T> std::vector<T> QList<T>::toStdVector() const + + Returns a std::vector object with the data contained in this QList. + Example: + + \snippet code/src_corelib_tools_qlist.cpp 17 + + \include containers-range-constructor.qdocinc + + \sa fromStdVector(), QList::toStdList() +*/ + +/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &vector) + \relates QList + + Writes the vector \a vector 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> &vector) + \relates QList + + Reads a vector from stream \a in into \a vector. + + This function requires the value type to implement \c operator>>(). + + \sa{Serializing Qt Data Types}{Format of the QDataStream operators} +*/ |