1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
7 \brief QVector is an alias for QList.
9 Please see the QList documentation for details.
15 \brief The QList class is a template class that provides a dynamic array.
22 QList<T> is one of Qt's generic \l{container classes}. It
23 stores its items in adjacent memory locations and provides fast
24 index-based access. QVector<T> used to be a different class in
25 Qt 5, but is now a simple alias to QList.
27 QList<T> and QVarLengthArray<T>
28 provide similar APIs and functionality. They are often interchangeable,
29 but there are performance consequences. Here is an overview of use cases:
32 \li QList should be your default first choice.
33 \li QVarLengthArray provides an array that reserves space on the stack,
34 but can dynamically grow onto the heap if required. It's good to
35 use for short lived containers that are usually small.
36 \li If you need a real linked list, which guarantees
37 \l{Algorithmic Complexity}{constant time} insertions mid-list and
38 uses iterators to items rather than indexes, use std::list.
41 \note QList and QVarLengthArray both guarantee C-compatible
43 \note QList in Qt 5 did not always have a C-compatible array layout and
44 we often recommended to use QVector instead for more predictable
45 performance. This is not the case in Qt 6 anymore, where both classes
46 now share an implementation and can be used interchangeably.
48 Here's an example of a QList that stores integers and a QList
49 that stores QString values:
51 \snippet code/src_corelib_tools_qlist.cpp 0
53 QList stores its items in an array of continuous memory. Typically, lists
54 are created with an initial size. For example, the following code
55 constructs a QList with 200 elements:
57 \snippet code/src_corelib_tools_qlist.cpp 1
59 The elements are automatically initialized with a
60 \l{default-constructed value}. If you want to initialize the
61 list with a different value, pass that value as the second
62 argument to the constructor:
64 \snippet code/src_corelib_tools_qlist.cpp 2
66 You can also call fill() at any time to fill the list with a
69 QList uses 0-based indexes, just like C++ arrays. To access the
70 item at a particular index position, you can use operator[](). On
71 non-const lists, operator[]() returns a reference to the item
72 that can be used on the left side of an assignment:
74 \snippet code/src_corelib_tools_qlist.cpp 3
76 For read-only access, an alternative syntax is to use at():
78 \snippet code/src_corelib_tools_qlist.cpp 4
80 at() can be faster than operator[](), because it never causes a
81 \l{deep copy} to occur.
83 Another way to access the data stored in a QList is to call
84 data(). The function returns a pointer to the first item in the
85 list. You can use the pointer to directly access and modify the
86 elements stored in the list. The pointer is also useful if you
87 need to pass a QList to a function that accepts a plain C++
90 If you want to find all occurrences of a particular value in a
91 list, use indexOf() or lastIndexOf(). The former searches
92 forward starting from a given index position, the latter searches
93 backward. Both return the index of the matching item if they found
94 one; otherwise, they return -1. For example:
96 \snippet code/src_corelib_tools_qlist.cpp 5
98 If you simply want to check whether a list contains a
99 particular value, use contains(). If you want to find out how
100 many times a particular value occurs in the list, use count().
102 QList provides these basic functions to add, move, and remove
103 items: insert(), replace(), remove(), prepend(), append(). With the
104 exception of append(), prepend() and replace(), these functions can be slow
105 (\l{linear time}) for large lists, because they require moving many items in
106 the list by one position in memory. If you want a container class that
107 provides fast insertion/removal in the middle, use std::list instead.
109 Unlike plain C++ arrays, QLists can be resized at any time by
110 calling resize(). If the new size is larger than the old size,
111 QList might need to reallocate the whole list. QList tries
112 to reduce the number of reallocations by preallocating up to twice
113 as much memory as the actual data needs.
115 If you're building a QList gradually and know in advance
116 approximately how many elements it will contain, you can call reserve(),
117 asking QList to preallocate a certain amount of memory.
118 You can also call capacity() to find out how much memory the
119 QList actually has allocated.
121 Note that using non-const operators and functions can cause QList
122 to do a deep copy of the data, due to \l{implicit sharing}.
124 QList's value type must be an \l{assignable data type}. This
125 covers most data types that are commonly used, but the compiler
126 won't let you, for example, store a QWidget as a value; instead,
127 store a QWidget *. A few functions have additional requirements;
128 for example, indexOf() and lastIndexOf() expect the value type to
129 support \c operator==(). These requirements are documented on a
132 For iterating over the items, see \l {Iterating over Containers}.
134 In addition to QList, Qt also provides QVarLengthArray, a very
135 low-level class with little functionality that is optimized for
138 \section2 More Information on Using Qt Containers
140 For a detailed discussion comparing Qt containers with each other and
141 with STL containers, see \l {Understand the Qt Containers}.
143 \section1 Maximum size and out-of-memory conditions
145 The maximum size of QList depends on the architecture. Most 64-bit
146 systems can allocate more than 2 GB of memory, with a typical limit
147 of 2^63 bytes. The actual value also depends on the overhead required for
148 managing the data block. As a result, you can expect the maximum size
149 of 2 GB minus overhead on 32-bit platforms, and 2^63 bytes minus overhead
150 on 64-bit platforms. The number of elements that can be stored in a
151 QList is this maximum size divided by the size of a stored element.
153 When memory allocation fails, QList uses the \l Q_CHECK_PTR macro,
154 which throws a \c std::bad_alloc exception if the application is being
155 compiled with exception support. If exceptions are disabled, then running
156 out of memory is undefined behavior.
158 Note that the operating system may impose further limits on applications
159 holding a lot of allocated memory, especially large, contiguous blocks.
160 Such considerations, the configuration of such behavior or any mitigation
161 are outside the scope of the Qt API.
165 \fn template <typename T> QList<T> QList<T>::mid(qsizetype pos, qsizetype length = -1) const
167 Returns a sub-list which contains elements from this list,
168 starting at position \a pos. If \a length is -1 (the default), all
169 elements after \a pos are included; otherwise \a length elements (or
170 all remaining elements if there are less than \a length elements)
175 \fn template <typename T> QList<T> QList<T>::first(qsizetype n) const
178 Returns a sub-list that contains the first \a n elements
181 \note The behavior is undefined when \a n < 0 or \a n > size().
187 \fn template <typename T> QList<T> QList<T>::last(qsizetype n) const
190 Returns a sub-list that contains the last \a n elements of this list.
192 \note The behavior is undefined when \a n < 0 or \a n > size().
194 \sa first(), sliced()
198 \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos, qsizetype n) const
201 Returns a sub-list that contains \a n elements of this list,
202 starting at position \a pos.
204 \note The behavior is undefined when \a pos < 0, \a n < 0,
205 or \a pos + \a n > size().
211 \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos) const
215 Returns a sub-list that contains the elements of this list starting at
216 position \a pos and extending to its end.
218 \note The behavior is undefined when \a pos < 0 or \a pos > size().
224/*! \fn template <typename T> QList<T>::QList()
226 Constructs an empty list.
232 \fn template <typename T> QList<T>::QList(QList<T> &&other)
234 Move-constructs a QList instance, making it point at the same
235 object that \a other was pointing to.
240/*! \fn template <typename T> QList<T>::QList(qsizetype size)
242 Constructs a list with an initial size of \a size elements.
244 The elements are initialized with a \l{default-constructed
250/*! \fn template <typename T> QList<T>::QList(qsizetype size, Qt::Initialization)
253 Constructs a list with an initial size of \a size elements.
255 QList will make an attempt at \b{not initializing} the elements.
257//! [qlist-uninitialized-strategy]
262 \li if \c{T} has a constructor that accepts \c{Qt::Uninitialized},
263 that constructor will be used to initialize the elements;
265 \li otherwise, each element is default constructed. For
266 trivially constructible types (such as \c{int}, \c{float}, etc.)
267 this is equivalent to not initializing them.
270//! [qlist-uninitialized-strategy]
272 \sa resizeForOverwrite()
275/*! \fn template <typename T> QList<T>::QList(qsizetype size, parameter_type value)
277 Constructs a list with an initial size of \a size elements.
278 Each element is initialized with \a value.
283/*! \fn template <typename T> QList<T>::QList(const QList<T> &other)
285 Constructs a copy of \a other.
287 This operation takes \l{Algorithmic Complexity}{constant time},
288 because QList is \l{implicitly shared}. This makes returning
289 a QList from a function very fast. If a shared instance is
290 modified, it will be copied (copy-on-write), and that takes
291 \l{Algorithmic Complexity}{linear time}.
296/*! \fn template <typename T> QList<T>::QList(std::initializer_list<T> args)
299 Constructs a list from the std::initializer_list given by \a args.
302/*! \fn template<typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator> = true> QList<T>::QList(InputIterator first, InputIterator last)
305 Constructs a list with the contents in the iterator range [\a first, \a last).
307 \note This constructor only participates in overload resolution if
308 \c InputIterator meets the requirements of a
309 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
311 The value type of \c InputIterator must be convertible to \c T.
314/*! \fn template <typename T> QList<T>::~QList()
319/*! \fn template <typename T> QList<T> &QList<T>::operator=(const QList<T> &other)
321 Assigns \a other to this list and returns a reference to this
326 \fn template <typename T> QList<T> &QList<T>::operator=(QList<T> &&other)
328 Move-assigns \a other to this QList instance.
334 \fn template <typename T> QList<T> &QList<T>::operator=(std::initializer_list<T> args)
337 Assigns the collection of values in \a args to this QList instance.
340/*! \fn template <typename T> void QList<T>::swap(QList<T> &other)
343 Swaps list \a other with this list. This operation is very fast and
347/*! \fn template <typename T> void QList<T>::swapItemsAt(qsizetype i, qsizetype j)
349 Exchange the item at index position \a i with the item at index
350 position \a j. This function assumes that both \a i and \a j are
351 at least 0 but less than size(). To avoid failure, test that both
352 \a i and \a j are at least 0 and less than size().
356/*! \fn template <typename T> bool QList<T>::operator==(const QList<T> &other) const
358 Returns \c true if \a other is equal to this list; otherwise
361 Two lists are considered equal if they contain the same values
364 This function requires the value type to have an implementation
370/*! \fn template <typename T> bool QList<T>::operator!=(const QList<T> &other) const
372 Returns \c true if \a other is not equal to this list; otherwise
375 Two lists are considered equal if they contain the same values
378 This function requires the value type to have an implementation
384/*! \fn template <typename T> bool QList<T>::operator<(const QList<T> &other) const
387 Returns \c true if this list is
388 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
389 {lexically less than} \a other; otherwise returns \c false.
391 This function requires the value type to have an implementation
395/*! \fn template <typename T> bool QList<T>::operator<=(const QList<T> &other) const
398 Returns \c true if this list is
399 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
400 {lexically less than or equal to} \a other; otherwise returns \c false.
402 This function requires the value type to have an implementation
406/*! \fn template <typename T> bool QList<T>::operator>(const QList<T> &other) const
409 Returns \c true if this list is
410 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
411 {lexically greater than} \a other; otherwise returns \c false.
413 This function requires the value type to have an implementation
417/*! \fn template <typename T> bool QList<T>::operator>=(const QList<T> &other) const
420 Returns \c true if this list is
421 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
422 {lexically greater than or equal to} \a other; otherwise returns \c false.
424 This function requires the value type to have an implementation
429 \fn template <typename T> size_t qHash(const QList<T> &key, size_t seed = 0)
433 Returns the hash value for \a key,
434 using \a seed to seed the calculation.
436 This function requires qHash() to be overloaded for the value type \c T.
439/*! \fn template <typename T> qsizetype QList<T>::size() const
441 Returns the number of items in the list.
443 \sa isEmpty(), resize()
446/*! \fn template <typename T> bool QList<T>::isEmpty() const
448 Returns \c true if the list has size 0; otherwise returns \c false.
453/*! \fn template <typename T> void QList<T>::resize(qsizetype size)
454 \fn template <typename T> void QList<T>::resize(qsizetype size, parameter_type c)
457 Sets the size of the list to \a size. If \a size is greater than the
458 current size, elements are added to the end; the new elements are
459 initialized with either a \l{default-constructed value} or \a c. If \a size
460 is less than the current size, elements are removed from the end.
462 If this list is not shared, the capacity() is preserved. Use squeeze()
463 to shed excess capacity.
465 \note In Qt versions prior to 5.7 (for QVector; QList lacked a resize()
466 until 6.0), this function released the memory used by the list instead of
467 preserving the capacity.
472/*! \fn template <typename T> void QList<T>::resizeForOverwrite(qsizetype size)
475 Sets the size of the list to \a size. If \a size is less than the
476 current size, elements are removed from the end. If \a size is
477 greater than the current size, elements are added to the end; QList
478 will make an attempt at \b{not initializing} these new elements.
480 \include qlist.qdoc qlist-uninitialized-strategy
483/*! \fn template <typename T> qsizetype QList<T>::capacity() const
485 Returns the maximum number of items that can be stored in the
486 list without forcing a reallocation.
488 The sole purpose of this function is to provide a means of fine
489 tuning QList's memory usage. In general, you will rarely ever
490 need to call this function. If you want to know how many items are
491 in the list, call size().
493 \note a statically allocated list will report a capacity of 0,
494 even if it's not empty.
496 \warning The free space position in the allocated memory block is undefined.
497 In other words, you should not assume that the free memory is always located
498 at the end of the list. You can call reserve() to ensure that there is
499 enough space at the end.
501 \sa reserve(), squeeze()
504/*! \fn template <typename T> void QList<T>::reserve(qsizetype size)
506 Attempts to allocate memory for at least \a size elements.
508 If you know in advance how large the list will be, you should call this
509 function to prevent reallocations and memory fragmentation. If you resize
510 the list often, you are also likely to get better performance.
512 If in doubt about how much space shall be needed, it is usually better to
513 use an upper bound as \a size, or a high estimate of the most likely size,
514 if a strict upper bound would be much bigger than this. If \a size is an
515 underestimate, the list will grow as needed once the reserved size is
516 exceeded, which may lead to a larger allocation than your best overestimate
517 would have and will slow the operation that triggers it.
519 \warning reserve() reserves memory but does not change the size of the
520 list. Accessing data beyond the current end of the list is
521 undefined behavior. If you need to access memory beyond the current end of
522 the list, use resize().
524 \sa squeeze(), capacity(), resize()
527/*! \fn template <typename T> void QList<T>::squeeze()
529 Releases any memory not required to store the items.
531 The sole purpose of this function is to provide a means of fine
532 tuning QList's memory usage. In general, you will rarely ever
533 need to call this function.
535 \sa reserve(), capacity()
538/*! \fn template <typename T> void QList<T>::detach()
543/*! \fn template <typename T> bool QList<T>::isDetached() const
548/*! \fn template <typename T> void QList<T>::setSharable(bool sharable)
553/*! \fn template <typename T> bool QList<T>::isSharedWith(const QList<T> &other) const
558/*! \fn template <typename T> T *QList<T>::data()
560 Returns a pointer to the data stored in the list. The pointer
561 can be used to access and modify the items in the list.
564 \snippet code/src_corelib_tools_qlist.cpp 6
566 \warning The pointer is invalidated on detachment or when the QList is
569 This function is mostly useful to pass a list to a function
570 that accepts a plain C++ array.
572 \sa constData(), operator[]()
575/*! \fn template <typename T> const T *QList<T>::data() const
580/*! \fn template <typename T> const T *QList<T>::constData() const
582 Returns a const pointer to the data stored in the list. The
583 pointer can be used to access the items in the list.
585 \warning The pointer is invalidated on detachment or when the QList is
588 This function is mostly useful to pass a list to a function
589 that accepts a plain C++ array.
591 \sa data(), operator[]()
594/*! \fn template <typename T> void QList<T>::clear()
596 Removes all the elements from the list.
598 If this list is not shared, the capacity() is preserved. Use squeeze() to
599 shed excess capacity.
601 \note In Qt versions prior to 5.7 (for QVector) and 6.0 (for QList), this
602 function released the memory used by the list instead of preserving the
605 \sa resize(), squeeze()
608/*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const
610 Returns the item at index position \a i in the list.
612 \a i must be a valid index position in the list (i.e., 0 <= \a
615 \sa value(), operator[]()
618/*! \fn template <typename T> T &QList<T>::operator[](qsizetype i)
620 Returns the item at index position \a i as a modifiable reference.
622 \a i must be a valid index position in the list (i.e., 0 <= \a i
625 Note that using non-const operators can cause QList to do a deep
631/*! \fn template <typename T> const T &QList<T>::operator[](qsizetype i) const
639 \fn template <typename T> void QList<T>::append(parameter_type value)
641 Inserts \a value at the end of the list.
644 \snippet code/src_corelib_tools_qlist.cpp 7
646 This is the same as calling resize(size() + 1) and assigning \a
647 value to the new last element in the list.
649 This operation is relatively fast, because QList typically
650 allocates more memory than necessary, so it can grow without
651 reallocating the entire list each time.
653 \sa operator<<(), prepend(), insert()
657 \fn template <typename T> void QList<T>::append(rvalue_ref value)
663 \snippet code/src_corelib_tools_qlist.cpp move-append
666/*! \fn template <typename T> void QList<T>::append(const QList<T> &value)
672 Appends the items of the \a value list to this list.
674 \sa operator<<(), operator+=()
677/*! \fn template <typename T> void QList<T>::append(QList<T> &&value)
682 Moves the items of the \a value list to the end of this list.
684 \sa operator<<(), operator+=()
688 \fn template <typename T> void QList<T>::prepend(parameter_type value)
689 \fn template <typename T> void QList<T>::prepend(rvalue_ref value)
691 Inserts \a value at the beginning of the list.
694 \snippet code/src_corelib_tools_qlist.cpp 8
696 This is the same as list.insert(0, \a value).
698 Normally this operation is relatively fast (amortized \l{constant time}).
699 QList is able to allocate extra memory at the beginning of the list data
700 and grow in that direction without reallocating or moving the data on each
701 operation. However if you want a container class with a guarantee of
702 \l{constant time} prepend, use std::list instead,
703 but prefer QList otherwise.
705 \sa append(), insert()
709 \fn template <typename T> template <typename ...Args> T &QList<T>::emplaceBack(Args&&... args)
710 \fn template <typename T> template <typename ...Args> T &QList<T>::emplace_back(Args&&... args)
712 Adds a new element to the end for the container. This new element
713 is constructed in-place using \a args as the arguments for its
716 Returns a reference to the new element.
719 \snippet code/src_corelib_tools_qlist.cpp emplace-back
721 It is also possible to access a newly created object by using
723 \snippet code/src_corelib_tools_qlist.cpp emplace-back-ref
725 This is the same as list.emplace(list.size(), \a args).
730/*! \fn template <typename T> void QList<T>::insert(qsizetype i, parameter_type value)
731 \fn template <typename T> void QList<T>::insert(qsizetype i, rvalue_ref value)
733 Inserts \a value at index position \a i in the list. If \a i is
734 0, the value is prepended to the list. If \a i is size(), the
735 value is appended to the list.
738 \snippet code/src_corelib_tools_qlist.cpp 9
740 For large lists, this operation can be slow (\l{linear time}),
741 because it requires moving all the items at indexes \a i and
742 above by one position further in memory. If you want a container
743 class that provides a fast insert() function, use std::list
746 \sa append(), prepend(), remove()
749/*! \fn template <typename T> void QList<T>::insert(qsizetype i, qsizetype count, parameter_type value)
753 Inserts \a count copies of \a value at index position \a i in the
757 \snippet code/src_corelib_tools_qlist.cpp 10
760/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, parameter_type value)
761 \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, rvalue_ref value)
765 Inserts \a value in front of the item pointed to by the iterator
766 \a before. Returns an iterator pointing at the inserted item.
769/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, qsizetype count, parameter_type value)
771 Inserts \a count copies of \a value in front of the item pointed to
772 by the iterator \a before. Returns an iterator pointing at the
773 first of the inserted items.
777 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(qsizetype i, Args&&... args)
779 Extends the container by inserting a new element at position \a i.
780 This new element is constructed in-place using \a args as the
781 arguments for its construction.
783 Returns an iterator to the new element.
786 \snippet code/src_corelib_tools_qlist.cpp emplace
788 \note It is guaranteed that the element will be created in place
789 at the beginning, but after that it might be copied or
790 moved to the right position.
796/*! \fn template <typename T> void QList<T>::replace(qsizetype i, parameter_type value)
797 \fn template <typename T> void QList<T>::replace(qsizetype i, rvalue_ref value)
799 Replaces the item at index position \a i with \a value.
801 \a i must be a valid index position in the list (i.e., 0 <= \a
804 \sa operator[](), remove()
807/*! \fn template <typename T> void QList<T>::remove(qsizetype i, qsizetype n = 1)
809 Removes \a n elements from the list, starting at index position \a i.
812 Element removal will preserve the list's capacity and not reduce the amount of
813 allocated memory. To shed extra capacity and free as much memory as possible,
817//! [iterator-invalidation-erase]
818 \note When QList is not \l{implicitly shared}, this function only
819 invalidates iterators at or after the specified position.
820//! [iterator-invalidation-erase]
822 \sa insert(), replace(), fill()
825/*! \fn template <typename T> void QList<T>::removeAt(qsizetype i)
828 Removes the element at index position \a i.
834 \include qlist.qdoc shrinking-erase
835 \include qlist.qdoc iterator-invalidation-erase
840/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::removeAll(const AT &t)
843 Removes all elements that compare equal to \a t from the
844 list. Returns the number of elements removed, if any.
846 \include qlist.qdoc shrinking-erase
851/*! \fn template <typename T> template <typename AT = T> bool QList<T>::removeOne(const AT &t)
854 Removes the first element that compares equal to \a t from the
855 list. Returns whether an element was, in fact, removed.
857 \include qlist.qdoc shrinking-erase
862/*! \fn template <typename T> template <typename Predicate> qsizetype QList<T>::removeIf(Predicate pred)
865 Removes all elements for which the predicate \a pred returns true
866 from the list. Returns the number of elements removed, if any.
871/*! \fn template <typename T> qsizetype QList<T>::length() const
874 Same as size() and count().
879/*! \fn template <typename T> T QList<T>::takeAt(qsizetype i)
882 Removes the element at index position \a i and returns it.
891 \include qlist.qdoc iterator-invalidation-erase
893 \sa takeFirst(), takeLast()
896/*! \fn template <typename T> void QList<T>::move(qsizetype from, qsizetype to)
899 Moves the item at index position \a from to index position \a to.
902/*! \fn template <typename T> void QList<T>::removeFirst()
904 Removes the first item in the list. Calling this function is
905 equivalent to calling remove(0). The list must not be empty. If
906 the list can be empty, call isEmpty() before calling this
909 \include qlist.qdoc shrinking-erase
911 \sa remove(), takeFirst(), isEmpty()
914/*! \fn template <typename T> void QList<T>::removeLast()
916 Removes the last item in the list. Calling this function is
917 equivalent to calling remove(size() - 1). The list must not be
918 empty. If the list can be empty, call isEmpty() before calling
921 \include qlist.qdoc shrinking-erase
923 \sa remove(), takeLast(), removeFirst(), isEmpty()
926/*! \fn template <typename T> T QList<T>::takeFirst()
929 Removes the first item in the list and returns it. This function
930 assumes the list is not empty. To avoid failure, call isEmpty()
931 before calling this function.
933 \sa takeLast(), removeFirst()
936/*! \fn template <typename T> T QList<T>::takeLast()
939 Removes the last item in the list and returns it. This function
940 assumes the list is not empty. To avoid failure, call isEmpty()
941 before calling this function.
943 If you don't use the return value, removeLast() is more
946 \sa takeFirst(), removeLast()
950 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(const_iterator before, Args&&... args)
954 Creates a new element in front of the item pointed to by the
955 iterator \a before. This new element is constructed in-place
956 using \a args as the arguments for its construction.
958 Returns an iterator to the new element.
961/*! \fn template <typename T> QList<T> &QList<T>::fill(parameter_type value, qsizetype size = -1)
963 Assigns \a value to all items in the list. If \a size is
964 different from -1 (the default), the list is resized to \a size beforehand.
967 \snippet code/src_corelib_tools_qlist.cpp 11
972/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::indexOf(const AT &value, qsizetype from = 0) const
974 Returns the index position of the first occurrence of \a value in
975 the list, searching forward from index position \a from.
976 Returns -1 if no item matched.
979 \snippet code/src_corelib_tools_qlist.cpp 12
981 This function requires the value type to have an implementation of
984 \sa lastIndexOf(), contains()
987/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::lastIndexOf(const AT &value, qsizetype from = -1) const
989 Returns the index position of the last occurrence of the value \a
990 value in the list, searching backward from index position \a
991 from. If \a from is -1 (the default), the search starts at the
992 last item. Returns -1 if no item matched.
995 \snippet code/src_corelib_tools_qlist.cpp 13
997 This function requires the value type to have an implementation of
1003/*! \fn template <typename T> template <typename AT = T> bool QList<T>::contains(const AT &value) const
1005 Returns \c true if the list contains an occurrence of \a value;
1006 otherwise returns \c false.
1008 This function requires the value type to have an implementation of
1011 \sa indexOf(), count()
1014/*! \fn template <typename T> bool QList<T>::startsWith(parameter_type value) const
1017 Returns \c true if this list is not empty and its first
1018 item is equal to \a value; otherwise returns \c false.
1020 \sa isEmpty(), first()
1023/*! \fn template <typename T> bool QList<T>::endsWith(parameter_type value) const
1026 Returns \c true if this list is not empty and its last
1027 item is equal to \a value; otherwise returns \c false.
1029 \sa isEmpty(), last()
1033/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::count(const AT &value) const
1035 Returns the number of occurrences of \a value in the list.
1037 This function requires the value type to have an implementation of
1040 \sa contains(), indexOf()
1043/*! \fn template <typename T> qsizetype QList<T>::count() const
1050/*! \fn template <typename T> QList<T>::iterator QList<T>::begin()
1052 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the
1053 first item in the list.
1055//! [iterator-invalidation-func-desc]
1056 \warning The returned iterator is invalidated on detachment or when the
1058//! [iterator-invalidation-func-desc]
1060 \sa constBegin(), end()
1063/*! \fn template <typename T> QList<T>::const_iterator QList<T>::begin() const
1068/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cbegin() const
1071 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1072 first item in the list.
1074 \include qlist.qdoc iterator-invalidation-func-desc
1079/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constBegin() const
1081 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1082 first item in the list.
1084 \include qlist.qdoc iterator-invalidation-func-desc
1086 \sa begin(), constEnd()
1089/*! \fn template <typename T> QList<T>::iterator QList<T>::end()
1091 Returns an \l{STL-style iterators}{STL-style iterator} pointing just after
1092 the last item in the list.
1094 \include qlist.qdoc iterator-invalidation-func-desc
1096 \sa begin(), constEnd()
1099/*! \fn template <typename T> QList<T>::const_iterator QList<T>::end() const
1104/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cend() const
1107 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1108 after the last item in the list.
1110 \include qlist.qdoc iterator-invalidation-func-desc
1115/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constEnd() const
1117 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1118 after the last item in the list.
1120 \include qlist.qdoc iterator-invalidation-func-desc
1122 \sa constBegin(), end()
1125/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rbegin()
1128 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to
1129 the first item in the list, in reverse order.
1131 \include qlist.qdoc iterator-invalidation-func-desc
1133 \sa begin(), crbegin(), rend()
1136/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rbegin() const
1141/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crbegin() const
1144 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1145 to the first item in the list, in reverse order.
1147 \include qlist.qdoc iterator-invalidation-func-desc
1149 \sa begin(), rbegin(), rend()
1152/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rend()
1155 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing just
1156 after the last item in the list, in reverse order.
1158 \include qlist.qdoc iterator-invalidation-func-desc
1160 \sa end(), crend(), rbegin()
1163/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rend() const
1168/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crend() const
1171 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1172 just after the last item in the list, in reverse order.
1174 \include qlist.qdoc iterator-invalidation-func-desc
1176 \sa end(), rend(), rbegin()
1179/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator pos)
1181 Removes the item pointed to by the iterator \a pos from the
1182 list, and returns an iterator to the next item in the list
1183 (which may be end()).
1185 \include qlist.qdoc shrinking-erase
1186 \include qlist.qdoc iterator-invalidation-erase
1188 \sa insert(), remove()
1191/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator begin, const_iterator end)
1195 Removes all the items from \a begin up to (but not including) \a
1196 end. Returns an iterator to the same item that \a end referred to
1199 \include qlist.qdoc shrinking-erase
1200 \include qlist.qdoc iterator-invalidation-erase
1203/*! \fn template <typename T> T& QList<T>::first()
1205 Returns a reference to the first item in the list. This
1206 function assumes that the list isn't empty.
1208 \sa last(), isEmpty(), constFirst()
1211/*! \fn template <typename T> const T& QList<T>::first() const
1216/*! \fn template <typename T> const T& QList<T>::constFirst() const
1219 Returns a const reference to the first item in the list. This
1220 function assumes that the list isn't empty.
1222 \sa constLast(), isEmpty(), first()
1225/*! \fn template <typename T> T& QList<T>::last()
1227 Returns a reference to the last item in the list. This function
1228 assumes that the list isn't empty.
1230 \sa first(), isEmpty(), constLast()
1233/*! \fn template <typename T> const T& QList<T>::last() const
1238/*! \fn template <typename T> const T& QList<T>::constLast() const
1241 Returns a const reference to the last item in the list. This function
1242 assumes that the list isn't empty.
1244 \sa constFirst(), isEmpty(), last()
1247/*! \fn template <typename T> T QList<T>::value(qsizetype i) const
1249 Returns the value at index position \a i in the list.
1251 If the index \a i is out of bounds, the function returns a
1252 \l{default-constructed value}. If you are certain that \a i is within
1253 bounds, you can use at() instead, which is slightly faster.
1255 \sa at(), operator[]()
1258/*! \fn template <typename T> T QList<T>::value(qsizetype i, parameter_type defaultValue) const
1262 If the index \a i is out of bounds, the function returns \a defaultValue.
1265/*! \fn template <typename T> void QList<T>::push_back(parameter_type value)
1267 This function is provided for STL compatibility. It is equivalent
1268 to append(\a value).
1271/*! \fn template <typename T> void QList<T>::push_back(rvalue_ref value)
1277 \fn template <typename T> void QList<T>::push_front(parameter_type value)
1278 \fn template <typename T> void QList<T>::push_front(rvalue_ref value)
1280 This function is provided for STL compatibility. It is equivalent
1281 to prepend(\a value).
1284/*! \fn template <typename T> void QList<T>::pop_front()
1286 This function is provided for STL compatibility. It is equivalent
1290/*! \fn template <typename T> void QList<T>::pop_back()
1292 This function is provided for STL compatibility. It is equivalent
1296/*! \fn template <typename T> T& QList<T>::front()
1298 This function is provided for STL compatibility. It is equivalent
1302/*! \fn template <typename T> QList<T>::const_reference QList<T>::front() const
1307/*! \fn template <typename T> QList<T>::reference QList<T>::back()
1309 This function is provided for STL compatibility. It is equivalent
1313/*! \fn template <typename T> QList<T>::const_reference QList<T>::back() const
1318/*! \fn template <typename T> void QList<T>::shrink_to_fit()
1321 This function is provided for STL compatibility. It is equivalent
1325/*! \fn template <typename T> bool QList<T>::empty() const
1327 This function is provided for STL compatibility. It is equivalent
1328 to isEmpty(), returning \c true if the list is empty; otherwise
1332/*! \fn template <typename T> qsizetype QList<T>::max_size()
1335 This function is provided for STL compatibility.
1336 It returns the maximum number of elements that the list can
1337 theoretically hold. In practice, the number can be much smaller,
1338 limited by the amount of memory available to the system.
1341/*! \fn template <typename T> QList<T> &QList<T>::operator+=(const QList<T> &other)
1343 Appends the items of the \a other list to this list and
1344 returns a reference to this list.
1346 \sa operator+(), append()
1349/*! \fn template <typename T> QList<T> &QList<T>::operator+=(QList<T> &&other)
1354 \sa operator+(), append()
1357/*! \fn template <typename T> void QList<T>::operator+=(parameter_type value)
1361 Appends \a value to the list.
1363 \sa append(), operator<<()
1366/*! \fn template <typename T> void QList<T>::operator+=(rvalue_ref value)
1371 \sa append(), operator<<()
1375 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const &
1376 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) &&
1377 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) const &
1378 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) &&
1380 Returns a list that contains all the items in this list
1381 followed by all the items in the \a other list.
1386/*! \fn template <typename T> QList<T> &QList<T>::operator<<(parameter_type value)
1388 Appends \a value to the list and returns a reference to this list.
1390 \sa append(), operator+=()
1393/*! \fn template <typename T> QList<T> &QList<T>::operator<<(rvalue_ref value)
1398 \sa append(), operator+=()
1402/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const QList<T> &other)
1404 Appends \a other to the list and returns a reference to the list.
1407/*! \fn template <typename T> QList<T> &QList<T>::operator<<(QList<T> &&other)
1413/*! \class QList::iterator
1415 \brief Provides an STL-style non-const iterator for QList and QStack.
1417 QList provides both \l{STL-style iterators} and \l{Java-style
1420//! [iterator-invalidation-class-desc]
1421 \warning Iterators on implicitly shared containers do not work
1422 exactly like STL-iterators. You should avoid copying a container
1423 while iterators are active on that container. For more information,
1424 read \l{Implicit sharing iterator problem}.
1426 \warning Iterators are invalidated when QList is modified. Consider that all
1427 iterators are invalidated by default. Exceptions to this rule are explicitly
1429//! [iterator-invalidation-class-desc]
1431 \sa QList::begin(), QList::end(), QList::const_iterator, QMutableListIterator
1434/*! \class QList::const_iterator
1436 \brief Provides an STL-style const iterator for QList and QStack.
1438 QList provides both \l{STL-style iterators} and \l{Java-style
1441 \include qlist.qdoc iterator-invalidation-class-desc
1443 \sa QList::constBegin(), QList::constEnd(), QList::iterator, QListIterator
1446/*! \typedef QList::reverse_iterator
1449 The QList::reverse_iterator typedef provides an STL-style non-const
1450 reverse iterator for QList.
1452 \include qlist.qdoc iterator-invalidation-class-desc
1454 \sa QList::rbegin(), QList::rend(), QList::const_reverse_iterator, QList::iterator
1457/*! \typedef QList::const_reverse_iterator
1460 The QList::const_reverse_iterator typedef provides an STL-style const
1461 reverse iterator for QList.
1463 \include qlist.qdoc iterator-invalidation-class-desc
1465 \sa QList::rbegin(), QList::rend(), QList::reverse_iterator, QList::const_iterator
1468/*! \typedef QList::Iterator
1470 Qt-style synonym for QList::iterator.
1473/*! \typedef QList::ConstIterator
1475 Qt-style synonym for QList::const_iterator.
1478/*! \typedef QList::const_pointer
1480 Provided for STL compatibility.
1483/*! \typedef QList::const_reference
1485 Provided for STL compatibility.
1488/*! \typedef QList::difference_type
1490 Provided for STL compatibility.
1493/*! \typedef QList::pointer
1495 Provided for STL compatibility.
1498/*! \typedef QList::reference
1500 Provided for STL compatibility.
1503/*! \typedef QList::size_type
1505 Provided for STL compatibility.
1508/*! \typedef QList::value_type
1510 Provided for STL compatibility.
1513/*! \typedef QList::parameter_type
1517/*! \typedef QList::rvalue_ref
1521/*! \fn template <typename T> QList<T> QList<T>::toList() const
1522 \fn template <typename T> QList<T> QList<T>::toVector() const
1525 A no-op in Qt 6. Provided for backwards compatibility with
1526 Qt 5, where QList and QVector where two different types.
1531/*! \fn template <typename T> QList<T> QList<T>::fromList(const QList<T> &list)
1532 \fn template <typename T> QList<T> QList<T>::fromVector(const QList<T> &list)
1535 A no-op in Qt 6. Provided for backwards compatibility with
1536 Qt 5, where QList and QVector were two different types.
1541/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list)
1544 Writes the list \a list to stream \a out.
1546 This function requires the value type to implement \c operator<<().
1548 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1551/*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list)
1554 Reads a list from stream \a in into \a list.
1556 This function requires the value type to implement \c operator>>().
1558 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1561/*! \fn template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t)
1565 Removes all elements that compare equal to \a t from the
1566 list \a list. Returns the number of elements removed, if any.
1568 \note Unlike QList::removeAll, \a t is not allowed to be a
1569 reference to an element inside \a list. If you cannot be sure that
1570 this is not the case, take a copy of \a t and call this function
1573 \sa QList::removeAll(), erase_if
1576/*! \fn template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred)
1580 Removes all elements for which the predicate \a pred returns true
1581 from the list \a list. Returns the number of elements removed, if
1587/*! \fn template <typename T> QList<T>& QList<T>::assign(qsizetype n, parameter_type t)
1590 Replaces the contents of this list with \a n copies of \a t.
1592 The size of this list will be equal to \a n.
1594 This function will only allocate memory if \a n exceeds the capacity of the
1595 list or this list is shared.
1598/*! \fn template <typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator>> QList<T>& QList<T>::assign(InputIterator first, InputIterator last)
1601 Replaces the contents of this list with a copy of the elements in the
1602 iterator range [\a first, \a last).
1604 The size of this list will be equal to the number of elements in the
1605 range [\a first, \a last).
1607 This function will only allocate memory if the number of elements in the
1608 range exceeds the capacity of this list or this list is shared.
1610 \note This function overload only participates in overload resolution if
1611 \c InputIterator meets the requirements of a
1612 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
1614 \note The behavior is undefined if either argument is an iterator into
1618/*! \fn template <typename T> QList<T>& QList<T>::assign(std::initializer_list<T> l)
1621 Replaces the contents of this list with a copy of the elements of
1624 The size of this list will be equal to the number of elements in
1627 This function only allocates memory if the number of elements in \a l
1628 exceeds the capacity of this list or this list is shared.