Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qlist.qdoc
Go to the documentation of this file.
1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \class QVector
6 \inmodule QtCore
7 \brief QVector is an alias for QList.
8
9 QVector<T> is a template class where \a T specifies the element type.
10
11 Please see the QList documentation for details.
12*/
13
14/*!
15 \class QList
16 \inmodule QtCore
17 \brief The QList class is a template class that provides a dynamic array.
18
19 \ingroup tools
20 \ingroup shared
21
22 \reentrant
23
24 QList<T> is one of Qt's generic \l{container classes}, where \a T
25 specifies the type of elements stored in the list. It stores its items
26 in adjacent memory locations and provides fast index-based access. QVector<T> used to be a different class in
27 Qt 5, but is now a simple alias to QList.
28
29 QList<T> and QVarLengthArray<T>
30 provide similar APIs and functionality. They are often interchangeable,
31 but there are performance consequences. Here is an overview of use cases:
32
33 \list
34 \li QList should be your default first choice.
35 \li QVarLengthArray provides an array that reserves space on the stack,
36 but can dynamically grow onto the heap if required. It's good to
37 use for short lived containers that are usually small.
38 \li If you need a real linked list, which guarantees
39 \l{Algorithmic Complexity}{constant time} insertions mid-list and
40 uses iterators to items rather than indexes, use std::list.
41 \endlist
42
43 \note QList and QVarLengthArray both guarantee C-compatible
44 array layout.
45 \note QList in Qt 5 did not always have a C-compatible array layout and
46 we often recommended to use QVector instead for more predictable
47 performance. This is not the case in Qt 6 anymore, where both classes
48 now share an implementation and can be used interchangeably.
49
50 Here's an example of a QList that stores integers and a QList
51 that stores QString values:
52
53 \snippet code/src_corelib_tools_qlist.cpp 0
54
55 QList stores its items in an array of continuous memory. Typically, lists
56 are created with an initial size. For example, the following code
57 constructs a QList with 200 elements:
58
59 \snippet code/src_corelib_tools_qlist.cpp 1
60
61 The elements are automatically initialized with a
62 \l{default-constructed value}. If you want to initialize the
63 list with a different value, pass that value as the second
64 argument to the constructor:
65
66 \snippet code/src_corelib_tools_qlist.cpp 2
67
68 You can also call fill() at any time to fill the list with a
69 value.
70
71 QList uses 0-based indexes, just like C++ arrays. To access the
72 item at a particular index position, you can use operator[](). On
73 non-const lists, operator[]() returns a reference to the item
74 that can be used on the left side of an assignment:
75
76 \snippet code/src_corelib_tools_qlist.cpp 3
77
78 For read-only access, an alternative syntax is to use at():
79
80 \snippet code/src_corelib_tools_qlist.cpp 4
81
82 at() can be faster than operator[](), because it never causes a
83 \l{deep copy} to occur.
84
85 Another way to access the data stored in a QList is to call
86 data(). The function returns a pointer to the first item in the
87 list. You can use the pointer to directly access and modify the
88 elements stored in the list. The pointer is also useful if you
89 need to pass a QList to a function that accepts a plain C++
90 array.
91
92 If you want to find all occurrences of a particular value in a
93 list, use indexOf() or lastIndexOf(). The former searches
94 forward starting from a given index position, the latter searches
95 backward. Both return the index of the matching item if they found
96 one; otherwise, they return -1. For example:
97
98 \snippet code/src_corelib_tools_qlist.cpp 5
99
100 If you simply want to check whether a list contains a
101 particular value, use contains(). If you want to find out how
102 many times a particular value occurs in the list, use count().
103
104 QList provides these basic functions to add, move, and remove
105 items: insert(), replace(), remove(), prepend(), append(). With the
106 exception of append(), prepend() and replace(), these functions can be slow
107 (\l{linear time}) for large lists, because they require moving many items in
108 the list by one position in memory. If you want a container class that
109 provides fast insertion/removal in the middle, use std::list instead.
110
111 Unlike plain C++ arrays, QLists can be resized at any time by
112 calling resize(). If the new size is larger than the old size,
113 QList might need to reallocate the whole list. QList tries
114 to reduce the number of reallocations by preallocating up to twice
115 as much memory as the actual data needs.
116
117 If you're building a QList gradually and know in advance
118 approximately how many elements it will contain, you can call reserve(),
119 asking QList to preallocate a certain amount of memory.
120 You can also call capacity() to find out how much memory the
121 QList actually has allocated.
122
123 Note that using non-const operators and functions can cause QList
124 to do a deep copy of the data, due to \l{implicit sharing}.
125
126 QList's value type must be an \l{assignable data type}. This
127 covers most data types that are commonly used, but the compiler
128 won't let you, for example, store a QWidget as a value; instead,
129 store a QWidget *. A few functions have additional requirements;
130 for example, indexOf() and lastIndexOf() expect the value type to
131 support \c operator==(). These requirements are documented on a
132 per-function basis.
133
134 For iterating over the items, see \l {Iterating over Containers}.
135 For using QList with functions from \c {<algorithm>} header, such as
136 \c {std::sort()}, \c {std::reverse()}, and \c {std::count_if()},
137 see \l {Qt containers and std algorithms}.
138
139 In addition to QList, Qt also provides QVarLengthArray, a very
140 low-level class with little functionality that is optimized for
141 speed.
142
143 \section2 More Information on Using Qt Containers
144
145 For a detailed discussion comparing Qt containers with each other and
146 with STL containers, see \l {Understand the Qt Containers}.
147
148 \section1 Maximum size and out-of-memory conditions
149
150 The maximum size of QList depends on the architecture. Most 64-bit
151 systems can allocate more than 2 GB of memory, with a typical limit
152 of 2^63 bytes. The actual value also depends on the overhead required for
153 managing the data block. As a result, you can expect the maximum size
154 of 2 GB minus overhead on 32-bit platforms, and 2^63 bytes minus overhead
155 on 64-bit platforms. The number of elements that can be stored in a
156 QList is this maximum size divided by the size of a stored element.
157
158 When memory allocation fails, QList uses the \l Q_CHECK_PTR macro,
159 which throws a \c std::bad_alloc exception if the application is being
160 compiled with exception support. If exceptions are disabled, then running
161 out of memory is undefined behavior.
162
163 Note that the operating system may impose further limits on applications
164 holding a lot of allocated memory, especially large, contiguous blocks.
165 Such considerations, the configuration of such behavior or any mitigation
166 are outside the scope of the Qt API.
167*/
168
169/*!
170 \fn template <typename T> QList<T> QList<T>::mid(qsizetype pos, qsizetype length = -1) const
171
172 Returns a sub-list which contains elements from this list,
173 starting at position \a pos. If \a length is -1 (the default), all
174 elements after \a pos are included; otherwise \a length elements (or
175 all remaining elements if there are less than \a length elements)
176 are included.
177*/
178
179/*!
180 \fn template <typename T> QList<T> QList<T>::first(qsizetype n) const
181 \since 6.0
182
183 Returns a sub-list that contains the first \a n elements
184 of this list.
185
186 \note The behavior is undefined when \a n < 0 or \a n > size().
187
188 \sa last(), sliced()
189*/
190
191/*!
192 \fn template <typename T> QList<T> QList<T>::last(qsizetype n) const
193 \since 6.0
194
195 Returns a sub-list that contains the last \a n elements of this list.
196
197 \note The behavior is undefined when \a n < 0 or \a n > size().
198
199 \sa first(), sliced()
200*/
201
202/*!
203 \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos, qsizetype n) const
204 \since 6.0
205
206 Returns a sub-list that contains \a n elements of this list,
207 starting at position \a pos.
208
209 \note The behavior is undefined when \a pos < 0, \a n < 0,
210 or \a pos + \a n > size().
211
212 \sa first(), last()
213*/
214
215/*!
216 \fn template <typename T> QList<T> QList<T>::sliced(qsizetype pos) const
217 \since 6.0
218 \overload
219
220 Returns a sub-list that contains the elements of this list starting at
221 position \a pos and extending to its end.
222
223 \note The behavior is undefined when \a pos < 0 or \a pos > size().
224
225 \sa first(), last()
226*/
227
228
229/*! \fn template <typename T> QList<T>::QList()
230
231 Constructs an empty list.
232
233 \sa resize()
234*/
235
236/*!
237 \fn template <typename T> QList<T>::QList(QList<T> &&other)
238
239 Move-constructs a QList instance, making it point at the same
240 object that \a other was pointing to.
241
242 \since 5.2
243*/
244
245/*! \fn template <typename T> QList<T>::QList(qsizetype size)
246
247 Constructs a list with an initial size of \a size elements.
248
249 The elements are initialized with a \l{default-constructed
250 value}.
251
252 \sa resize()
253*/
254
255/*! \fn template <typename T> QList<T>::QList(qsizetype size, Qt::Initialization)
256 \since 6.8
257
258 Constructs a list with an initial size of \a size elements.
259
260 QList will make an attempt at \b{not initializing} the elements.
261
262//! [qlist-uninitialized-strategy]
263 Specifically:
264
265 \list
266
267 \li if \c{T} has a constructor that accepts \c{Qt::Uninitialized},
268 that constructor will be used to initialize the elements;
269
270 \li otherwise, each element is default constructed. For
271 trivially constructible types (such as \c{int}, \c{float}, etc.)
272 this is equivalent to not initializing them.
273
274 \endlist
275//! [qlist-uninitialized-strategy]
276
277 \sa resizeForOverwrite()
278*/
279
280/*! \fn template <typename T> QList<T>::QList(qsizetype size, parameter_type value)
281
282 Constructs a list with an initial size of \a size elements.
283 Each element is initialized with \a value.
284
285 \sa resize(), fill()
286*/
287
288/*! \fn template <typename T> QList<T>::QList(const QList<T> &other)
289
290 Constructs a copy of \a other.
291
292 This operation takes \l{Algorithmic Complexity}{constant time},
293 because QList is \l{implicitly shared}. This makes returning
294 a QList from a function very fast. If a shared instance is
295 modified, it will be copied (copy-on-write), and that takes
296 \l{Algorithmic Complexity}{linear time}.
297
298 \sa operator=()
299*/
300
301/*! \fn template <typename T> QList<T>::QList(std::initializer_list<T> args)
302 \since 4.8
303
304 Constructs a list from the std::initializer_list given by \a args.
305*/
306
307/*! \fn template<typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator> = true> QList<T>::QList(InputIterator first, InputIterator last)
308 \since 5.14
309
310 Constructs a list with the contents in the iterator range [\a first, \a last).
311
312 The value type of \c InputIterator must be convertible to \c T.
313
314 \constraints
315 \c InputIterator meets the requirements of a
316 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
317*/
318
319/*! \fn template <typename T> QList<T>::~QList()
320
321 Destroys the list.
322*/
323
324/*! \fn template <typename T> QList<T> &QList<T>::operator=(const QList<T> &other)
325
326 Assigns \a other to this list and returns a reference to this
327 list.
328*/
329
330/*!
331 \fn template <typename T> QList<T> &QList<T>::operator=(QList<T> &&other)
332
333 Move-assigns \a other to this QList instance.
334
335 \since 5.2
336*/
337
338/*!
339 \fn template <typename T> QList<T> &QList<T>::operator=(std::initializer_list<T> args)
340 \since 5.14
341
342 Assigns the collection of values in \a args to this QList instance.
343*/
344
345/*! \fn template <typename T> void QList<T>::swap(QList<T> &other)
346 \since 4.8
347 \memberswap{list}
348*/
349
350/*! \fn template <typename T> void QList<T>::swapItemsAt(qsizetype i, qsizetype j)
351
352 Exchange the item at index position \a i with the item at index
353 position \a j. This function assumes that both \a i and \a j are
354 at least 0 but less than size(). To avoid failure, test that both
355 \a i and \a j are at least 0 and less than size().
356*/
357
358
359/*! \fn template <typename T> bool QList<T>::operator==(const QList<T> &other) const
360
361 Returns \c true if \a other is equal to this list; otherwise
362 returns \c false.
363
364 Two lists are considered equal if they contain the same values
365 in the same order.
366
367 This function requires the value type to have an implementation
368 of \c operator==().
369
370 \sa operator!=()
371*/
372
373/*! \fn template <typename T> bool QList<T>::operator!=(const QList<T> &other) const
374
375 Returns \c true if \a other is not equal to this list; otherwise
376 returns \c false.
377
378 Two lists are considered equal if they contain the same values
379 in the same order.
380
381 This function requires the value type to have an implementation
382 of \c operator==().
383
384 \sa operator==()
385*/
386
387/*! \fn template <typename T> bool QList<T>::operator<(const QList<T> &other) const
388 \since 5.6
389
390 Returns \c true if this list is
391 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
392 {lexically less than} \a other; otherwise returns \c false.
393
394 This function requires the value type to have an implementation
395 of \c operator<().
396*/
397
398/*! \fn template <typename T> bool QList<T>::operator<=(const QList<T> &other) const
399 \since 5.6
400
401 Returns \c true if this list is
402 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
403 {lexically less than or equal to} \a other; otherwise returns \c false.
404
405 This function requires the value type to have an implementation
406 of \c operator<().
407*/
408
409/*! \fn template <typename T> bool QList<T>::operator>(const QList<T> &other) const
410 \since 5.6
411
412 Returns \c true if this list is
413 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
414 {lexically greater than} \a other; otherwise returns \c false.
415
416 This function requires the value type to have an implementation
417 of \c operator<().
418*/
419
420/*! \fn template <typename T> bool QList<T>::operator>=(const QList<T> &other) const
421 \since 5.6
422
423 Returns \c true if this list is
424 \l{http://en.cppreference.com/w/cpp/algorithm/lexicographical_compare}
425 {lexically greater than or equal to} \a other; otherwise returns \c false.
426
427 This function requires the value type to have an implementation
428 of \c operator<().
429*/
430
431/*!
432 \fn template <typename T> auto QList<T>::operator<=>(const QList<T> &lhs, const QList<T> &rhs)
433 \since 6.9
434
435 Compares the contents of \a lhs and \a rhs
436 \l {https://en.cppreference.com/w/cpp/algorithm/lexicographical_compare_three_way}
437 {lexicographically}. Returns the result of the strongest applicable category
438 type, that is \c {decltype(lhs[0] <=> rhs[0])} if \c {operator<=>()} is
439 available for type \c {T}; otherwise \c {std::weak_ordering}.
440
441 \note This operator is only available in C++20 mode, and when the underlying
442 type \c T models the \c {std::three_way_comparable} concept
443 or provides \c {operator<()}.
444*/
445
446/*!
447 \fn template <typename T> size_t qHash(const QList<T> &key, size_t seed = 0)
448 \since 5.6
449 \qhasholdT{QList}{T}
450*/
451
452/*! \fn template <typename T> qsizetype QList<T>::size() const
453
454 Returns the number of items in the list.
455
456 \sa isEmpty(), resize()
457*/
458
459/*! \fn template <typename T> bool QList<T>::isEmpty() const
460
461 Returns \c true if the list has size 0; otherwise returns \c false.
462
463 \sa size(), resize()
464*/
465
466/*! \fn template <typename T> void QList<T>::resize(qsizetype size)
467 \fn template <typename T> void QList<T>::resize(qsizetype size, parameter_type c)
468 \since 6.0
469
470 Sets the size of the list to \a size. If \a size is greater than the
471 current size, elements are added to the end; the new elements are
472 initialized with either a \l{default-constructed value} or \a c. If \a size
473 is less than the current size, elements are removed from the end.
474
475 If this list is not shared, the capacity() is preserved. Use squeeze()
476 to shed excess capacity.
477
478 \note In Qt versions prior to 5.7 (for QVector; QList lacked a resize()
479 until 6.0), this function released the memory used by the list instead of
480 preserving the capacity.
481
482 \sa size()
483*/
484
485/*! \fn template <typename T> void QList<T>::resizeForOverwrite(qsizetype size)
486 \since 6.8
487
488 Sets the size of the list to \a size. If \a size is less than the
489 current size, elements are removed from the end. If \a size is
490 greater than the current size, elements are added to the end; QList
491 will make an attempt at \b{not initializing} these new elements.
492
493 \include qlist.qdoc qlist-uninitialized-strategy
494*/
495
496/*! \fn template <typename T> qsizetype QList<T>::capacity() const
497
498 Returns the maximum number of items that can be stored in the
499 list without forcing a reallocation.
500
501 The sole purpose of this function is to provide a means of fine
502 tuning QList's memory usage. In general, you will rarely ever
503 need to call this function. If you want to know how many items are
504 in the list, call size().
505
506 \note a statically allocated list will report a capacity of 0,
507 even if it's not empty.
508
509 \warning The free space position in the allocated memory block is undefined.
510 In other words, you should not assume that the free memory is always located
511 at the end of the list. You can call reserve() to ensure that there is
512 enough space at the end.
513
514 \sa reserve(), squeeze()
515*/
516
517/*! \fn template <typename T> void QList<T>::reserve(qsizetype size)
518
519 Attempts to allocate memory for at least \a size elements.
520
521 If you know in advance how large the list will be, you should call this
522 function to prevent reallocations and memory fragmentation. If you resize
523 the list often, you are also likely to get better performance.
524
525 If in doubt about how much space shall be needed, it is usually better to
526 use an upper bound as \a size, or a high estimate of the most likely size,
527 if a strict upper bound would be much bigger than this. If \a size is an
528 underestimate, the list will grow as needed once the reserved size is
529 exceeded, which may lead to a larger allocation than your best overestimate
530 would have and will slow the operation that triggers it.
531
532 \warning reserve() reserves memory but does not change the size of the
533 list. Accessing data beyond the current end of the list is
534 undefined behavior. If you need to access memory beyond the current end of
535 the list, use resize().
536
537 \sa squeeze(), capacity(), resize()
538*/
539
540/*! \fn template <typename T> void QList<T>::squeeze()
541
542 Releases any memory not required to store the items.
543
544 The sole purpose of this function is to provide a means of fine
545 tuning QList's memory usage. In general, you will rarely ever
546 need to call this function.
547
548 \sa reserve(), capacity()
549*/
550
551/*! \fn template <typename T> void QList<T>::detach()
552
553 Ensures that this QList's data is no longer
554 \l{Implicit Sharing}{shared} with other instances.
555*/
556
557/*! \fn template <typename T> bool QList<T>::isDetached() const
558
559 \internal
560*/
561
562/*! \fn template <typename T> void QList<T>::setSharable(bool sharable)
563
564 \internal
565*/
566
567/*! \fn template <typename T> bool QList<T>::isSharedWith(const QList<T> &other) const
568
569 \internal
570*/
571
572/*! \fn template <typename T> T *QList<T>::data()
573
574 Returns a pointer to the data stored in the list. The pointer
575 can be used to access and modify the items in the list.
576
577 Example:
578 \snippet code/src_corelib_tools_qlist.cpp 6
579
580 \warning The pointer is invalidated on detachment or when the QList is
581 modified.
582
583 This function is mostly useful to pass a list to a function
584 that accepts a plain C++ array.
585
586 \sa constData(), operator[]()
587*/
588
589/*! \fn template <typename T> const T *QList<T>::data() const
590
591 \overload
592*/
593
594/*! \fn template <typename T> const T *QList<T>::constData() const
595
596 Returns a const pointer to the data stored in the list. The
597 pointer can be used to access the items in the list.
598
599 \warning The pointer is invalidated on detachment or when the QList is
600 modified.
601
602 This function is mostly useful to pass a list to a function
603 that accepts a plain C++ array.
604
605 \sa data(), operator[]()
606*/
607
608/*! \fn template <typename T> void QList<T>::clear()
609
610 Removes all the elements from the list.
611
612 If this list is not shared, the capacity() is preserved. Use squeeze() to
613 shed excess capacity.
614
615 \note In Qt versions prior to 5.7 (for QVector) and 6.0 (for QList), this
616 function released the memory used by the list instead of preserving the
617 capacity.
618
619 \sa resize(), squeeze()
620*/
621
622/*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const
623
624 Returns the item at index position \a i in the list.
625
626 \a i must be a valid index position in the list (i.e., 0 <= \a
627 i < size()).
628
629 \sa value(), operator[]()
630*/
631
632/*! \fn template <typename T> T &QList<T>::operator[](qsizetype i)
633
634 Returns the item at index position \a i as a modifiable reference.
635
636 \a i must be a valid index position in the list (i.e., 0 <= \a i
637 < size()).
638
639 Note that using non-const operators can cause QList to do a deep
640 copy.
641
642 \sa at(), value()
643*/
644
645/*! \fn template <typename T> const T &QList<T>::operator[](qsizetype i) const
646
647 \overload
648
649 Same as at(\a i).
650*/
651
652/*!
653 \fn template <typename T> void QList<T>::append(parameter_type value)
654
655 Inserts \a value at the end of the list.
656
657 Example:
658 \snippet code/src_corelib_tools_qlist.cpp 7
659
660 This is the same as calling resize(size() + 1) and assigning \a
661 value to the new last element in the list.
662
663 This operation is relatively fast, because QList typically
664 allocates more memory than necessary, so it can grow without
665 reallocating the entire list each time.
666
667 \sa operator<<(), prepend(), insert()
668*/
669
670/*!
671 \fn template <typename T> void QList<T>::append(rvalue_ref value)
672 \since 5.6
673
674 \overload
675
676 Example:
677 \snippet code/src_corelib_tools_qlist.cpp move-append
678*/
679
680/*! \fn template <typename T> void QList<T>::append(const QList<T> &value)
681
682 \overload
683
684 \since 5.5
685
686 Appends the items of the \a value list to this list.
687
688 \sa operator<<(), operator+=()
689*/
690
691/*! \fn template <typename T> void QList<T>::append(QList<T> &&value)
692 \overload
693
694 \since 6.0
695
696 Moves the items of the \a value list to the end of this list.
697
698 \sa operator<<(), operator+=()
699*/
700
701/*!
702 \fn template <typename T> void QList<T>::prepend(parameter_type value)
703 \fn template <typename T> void QList<T>::prepend(rvalue_ref value)
704
705 Inserts \a value at the beginning of the list.
706
707 Example:
708 \snippet code/src_corelib_tools_qlist.cpp 8
709
710 This is the same as list.insert(0, \a value).
711
712 Normally this operation is relatively fast (amortized \l{constant time}).
713 QList is able to allocate extra memory at the beginning of the list data
714 and grow in that direction without reallocating or moving the data on each
715 operation. However if you want a container class with a guarantee of
716 \l{constant time} prepend, use std::list instead,
717 but prefer QList otherwise.
718
719 \sa append(), insert()
720*/
721
722/*!
723 \fn template <typename T> template <typename ...Args> T &QList<T>::emplaceBack(Args&&... args)
724 \fn template <typename T> template <typename ...Args> T &QList<T>::emplace_back(Args&&... args)
725
726 Adds a new element to the end for the container. This new element
727 is constructed in-place using \a args as the arguments for its
728 construction.
729
730 Returns a reference to the new element.
731
732 Example:
733 \snippet code/src_corelib_tools_qlist.cpp emplace-back
734
735 It is also possible to access a newly created object by using
736 returned reference:
737 \snippet code/src_corelib_tools_qlist.cpp emplace-back-ref
738
739 This is the same as list.emplace(list.size(), \a args).
740
741 \sa emplace
742*/
743
744/*! \fn template <typename T> void QList<T>::insert(qsizetype i, parameter_type value)
745 \fn template <typename T> void QList<T>::insert(qsizetype i, rvalue_ref value)
746
747 Inserts \a value at index position \a i in the list. If \a i is
748 0, the value is prepended to the list. If \a i is size(), the
749 value is appended to the list.
750
751 Example:
752 \snippet code/src_corelib_tools_qlist.cpp 9
753
754 For large lists, this operation can be slow (\l{linear time}),
755 because it requires moving all the items at indexes \a i and
756 above by one position further in memory. If you want a container
757 class that provides a fast insert() function, use std::list
758 instead.
759
760 \sa append(), prepend(), remove()
761*/
762
763/*! \fn template <typename T> void QList<T>::insert(qsizetype i, qsizetype count, parameter_type value)
764
765 \overload
766
767 Inserts \a count copies of \a value at index position \a i in the
768 list.
769
770 Example:
771 \snippet code/src_corelib_tools_qlist.cpp 10
772*/
773
774/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, parameter_type value)
775 \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, rvalue_ref value)
776
777 \overload
778
779 Inserts \a value in front of the item pointed to by the iterator
780 \a before. Returns an iterator pointing at the inserted item.
781*/
782
783/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, qsizetype count, parameter_type value)
784
785 Inserts \a count copies of \a value in front of the item pointed to
786 by the iterator \a before. Returns an iterator pointing at the
787 first of the inserted items.
788*/
789
790/*!
791 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(qsizetype i, Args&&... args)
792
793 Extends the container by inserting a new element at position \a i.
794 This new element is constructed in-place using \a args as the
795 arguments for its construction.
796
797 Returns an iterator to the new element.
798
799 Example:
800 \snippet code/src_corelib_tools_qlist.cpp emplace
801
802 \note It is guaranteed that the element will be created in place
803 at the beginning, but after that it might be copied or
804 moved to the right position.
805
806 \sa emplaceBack
807*/
808
809
810/*! \fn template <typename T> void QList<T>::replace(qsizetype i, parameter_type value)
811 \fn template <typename T> void QList<T>::replace(qsizetype i, rvalue_ref value)
812
813 Replaces the item at index position \a i with \a value.
814
815 \a i must be a valid index position in the list (i.e., 0 <= \a
816 i < size()).
817
818 \sa operator[](), remove()
819*/
820
821/*! \fn template <typename T> void QList<T>::remove(qsizetype i, qsizetype n = 1)
822
823 Removes \a n elements from the list, starting at index position \a i.
824
825//! [shrinking-erase]
826 Element removal will preserve the list's capacity and not reduce the amount of
827 allocated memory. To shed extra capacity and free as much memory as possible,
828 call squeeze().
829//! [shrinking-erase]
830
831//! [iterator-invalidation-erase]
832 \note When QList is not \l{implicitly shared}, this function only
833 invalidates iterators at or after the specified position.
834//! [iterator-invalidation-erase]
835
836 \sa insert(), replace(), fill()
837*/
838
839/*! \fn template <typename T> void QList<T>::removeAt(qsizetype i)
840 \since 5.2
841
842 Removes the element at index position \a i.
843 Equivalent to
844 \code
845 remove(i);
846 \endcode
847
848 \include qlist.qdoc shrinking-erase
849 \include qlist.qdoc iterator-invalidation-erase
850
851 \sa remove()
852*/
853
854/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::removeAll(const AT &t)
855 \since 5.4
856
857 Removes all elements that compare equal to \a t from the
858 list. Returns the number of elements removed, if any.
859
860 \include qlist.qdoc shrinking-erase
861
862 \sa removeOne()
863*/
864
865/*! \fn template <typename T> template <typename AT = T> bool QList<T>::removeOne(const AT &t)
866 \since 5.4
867
868 Removes the first element that compares equal to \a t from the
869 list. Returns whether an element was, in fact, removed.
870
871 \include qlist.qdoc shrinking-erase
872
873 \sa removeAll()
874*/
875
876/*! \fn template <typename T> template <typename Predicate> qsizetype QList<T>::removeIf(Predicate pred)
877 \since 6.1
878
879 Removes all elements for which the predicate \a pred returns true
880 from the list. Returns the number of elements removed, if any.
881
882 \sa removeAll()
883*/
884
885/*! \fn template <typename T> qsizetype QList<T>::length() const
886 \since 5.2
887
888 Same as size() and count().
889
890 \sa size(), count()
891*/
892
893/*! \fn template <typename T> T QList<T>::takeAt(qsizetype i)
894 \since 5.2
895
896 Removes the element at index position \a i and returns it.
897
898 Equivalent to
899 \code
900 T t = at(i);
901 remove(i);
902 return t;
903 \endcode
904
905 \include qlist.qdoc iterator-invalidation-erase
906
907 \sa takeFirst(), takeLast()
908*/
909
910/*! \fn template <typename T> void QList<T>::move(qsizetype from, qsizetype to)
911 \since 5.6
912
913 Moves the item at index position \a from to index position \a to.
914
915 \c from and \c to must be within bounds.
916
917 For example, to move the first item to the end of the list:
918 \code
919 QList<int> list = {1, 2, 3};
920 list.move(0, list.size() - 1);
921 qDebug() << list; // Prints "QList(2, 3, 1)"
922 \endcode
923*/
924
925/*! \fn template <typename T> void QList<T>::removeFirst()
926 \since 5.1
927 Removes the first item in the list. Calling this function is
928 equivalent to calling remove(0). The list must not be empty. If
929 the list can be empty, call isEmpty() before calling this
930 function.
931
932 \include qlist.qdoc shrinking-erase
933
934 \sa remove(), takeFirst(), isEmpty()
935*/
936
937/*! \fn template <typename T> void QList<T>::removeLast()
938 \since 5.1
939 Removes the last item in the list. Calling this function is
940 equivalent to calling remove(size() - 1). The list must not be
941 empty. If the list can be empty, call isEmpty() before calling
942 this function.
943
944 \include qlist.qdoc shrinking-erase
945
946 \sa remove(), takeLast(), removeFirst(), isEmpty()
947*/
948
949/*! \fn template <typename T> T QList<T>::takeFirst()
950 \since 5.1
951
952 Removes the first item in the list and returns it. This function
953 assumes the list is not empty. To avoid failure, call isEmpty()
954 before calling this function.
955
956 \sa takeLast(), removeFirst()
957*/
958
959/*! \fn template <typename T> T QList<T>::takeLast()
960 \since 5.1
961
962 Removes the last item in the list and returns it. This function
963 assumes the list is not empty. To avoid failure, call isEmpty()
964 before calling this function.
965
966 If you don't use the return value, removeLast() is more
967 efficient.
968
969 \sa takeFirst(), removeLast()
970*/
971
972/*!
973 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(const_iterator before, Args&&... args)
974
975 \overload
976
977 Creates a new element in front of the item pointed to by the
978 iterator \a before. This new element is constructed in-place
979 using \a args as the arguments for its construction.
980
981 Returns an iterator to the new element.
982*/
983
984/*! \fn template <typename T> QList<T> &QList<T>::fill(parameter_type value, qsizetype size = -1)
985
986 Assigns \a value to all items in the list. If \a size is
987 different from -1 (the default), the list is resized to \a size beforehand.
988
989 Example:
990 \snippet code/src_corelib_tools_qlist.cpp 11
991
992 \sa resize()
993*/
994
995/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::indexOf(const AT &value, qsizetype from = 0) const
996
997 Returns the index position of the first occurrence of \a value in
998 the list, searching forward from index position \a from.
999 Returns -1 if no item matched.
1000
1001 Example:
1002 \snippet code/src_corelib_tools_qlist.cpp 12
1003
1004 This function requires the value type to have an implementation of
1005 \c operator==().
1006
1007 \sa lastIndexOf(), contains()
1008*/
1009
1010/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::lastIndexOf(const AT &value, qsizetype from = -1) const
1011
1012 Returns the index position of the last occurrence of the value \a
1013 value in the list, searching backward from index position \a
1014 from. If \a from is -1 (the default), the search starts at the
1015 last item. Returns -1 if no item matched.
1016
1017 Example:
1018 \snippet code/src_corelib_tools_qlist.cpp 13
1019
1020 This function requires the value type to have an implementation of
1021 \c operator==().
1022
1023 \sa indexOf()
1024*/
1025
1026/*! \fn template <typename T> template <typename AT = T> bool QList<T>::contains(const AT &value) const
1027
1028 Returns \c true if the list contains an occurrence of \a value;
1029 otherwise returns \c false.
1030
1031 This function requires the value type to have an implementation of
1032 \c operator==().
1033
1034 \sa indexOf(), count()
1035*/
1036
1037/*! \fn template <typename T> bool QList<T>::startsWith(parameter_type value) const
1038 \since 4.5
1039
1040 Returns \c true if this list is not empty and its first
1041 item is equal to \a value; otherwise returns \c false.
1042
1043 \sa isEmpty(), first()
1044*/
1045
1046/*! \fn template <typename T> bool QList<T>::endsWith(parameter_type value) const
1047 \since 4.5
1048
1049 Returns \c true if this list is not empty and its last
1050 item is equal to \a value; otherwise returns \c false.
1051
1052 \sa isEmpty(), last()
1053*/
1054
1055
1056/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::count(const AT &value) const
1057
1058 Returns the number of occurrences of \a value in the list.
1059
1060 This function requires the value type to have an implementation of
1061 \c operator==().
1062
1063 \sa contains(), indexOf()
1064*/
1065
1066/*! \fn template <typename T> qsizetype QList<T>::count() const
1067
1068 \overload
1069
1070 Same as size().
1071*/
1072
1073/*! \fn template <typename T> QList<T>::iterator QList<T>::begin()
1074
1075 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the
1076 first item in the list.
1077
1078//! [iterator-invalidation-func-desc]
1079 \warning The returned iterator is invalidated on detachment or when the
1080 QList is modified.
1081//! [iterator-invalidation-func-desc]
1082
1083 \sa constBegin(), end()
1084*/
1085
1086/*! \fn template <typename T> QList<T>::const_iterator QList<T>::begin() const
1087
1088 \overload
1089*/
1090
1091/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cbegin() const
1092 \since 5.0
1093
1094 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1095 first item in the list.
1096
1097 \include qlist.qdoc iterator-invalidation-func-desc
1098
1099 \sa begin(), cend()
1100*/
1101
1102/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constBegin() const
1103
1104 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1105 first item in the list.
1106
1107 \include qlist.qdoc iterator-invalidation-func-desc
1108
1109 \sa begin(), constEnd()
1110*/
1111
1112/*! \fn template <typename T> QList<T>::iterator QList<T>::end()
1113
1114 Returns an \l{STL-style iterators}{STL-style iterator} pointing just after
1115 the last item in the list.
1116
1117 \include qlist.qdoc iterator-invalidation-func-desc
1118
1119 \sa begin(), constEnd()
1120*/
1121
1122/*! \fn template <typename T> QList<T>::const_iterator QList<T>::end() const
1123
1124 \overload
1125*/
1126
1127/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cend() const
1128 \since 5.0
1129
1130 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1131 after the last item in the list.
1132
1133 \include qlist.qdoc iterator-invalidation-func-desc
1134
1135 \sa cbegin(), end()
1136*/
1137
1138/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constEnd() const
1139
1140 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1141 after the last item in the list.
1142
1143 \include qlist.qdoc iterator-invalidation-func-desc
1144
1145 \sa constBegin(), end()
1146*/
1147
1148/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rbegin()
1149 \since 5.6
1150
1151 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to
1152 the first item in the list, in reverse order.
1153
1154 \include qlist.qdoc iterator-invalidation-func-desc
1155
1156 \sa begin(), crbegin(), rend()
1157*/
1158
1159/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rbegin() const
1160 \since 5.6
1161 \overload
1162*/
1163
1164/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crbegin() const
1165 \since 5.6
1166
1167 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1168 to the first item in the list, in reverse order.
1169
1170 \include qlist.qdoc iterator-invalidation-func-desc
1171
1172 \sa begin(), rbegin(), rend()
1173*/
1174
1175/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rend()
1176 \since 5.6
1177
1178 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing just
1179 after the last item in the list, in reverse order.
1180
1181 \include qlist.qdoc iterator-invalidation-func-desc
1182
1183 \sa end(), crend(), rbegin()
1184*/
1185
1186/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rend() const
1187 \since 5.6
1188 \overload
1189*/
1190
1191/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crend() const
1192 \since 5.6
1193
1194 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1195 just after the last item in the list, in reverse order.
1196
1197 \include qlist.qdoc iterator-invalidation-func-desc
1198
1199 \sa end(), rend(), rbegin()
1200*/
1201
1202/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator pos)
1203
1204 Removes the item pointed to by the iterator \a pos from the
1205 list, and returns an iterator to the next item in the list
1206 (which may be end()).
1207
1208 \include qlist.qdoc shrinking-erase
1209 \include qlist.qdoc iterator-invalidation-erase
1210
1211 \sa insert(), remove()
1212*/
1213
1214/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator begin, const_iterator end)
1215
1216 \overload
1217
1218 Removes all the items from \a begin up to (but not including) \a
1219 end. Returns an iterator to the same item that \a end referred to
1220 before the call.
1221
1222 \include qlist.qdoc shrinking-erase
1223 \include qlist.qdoc iterator-invalidation-erase
1224*/
1225
1226/*! \fn template <typename T> T& QList<T>::first()
1227
1228 Returns a reference to the first item in the list. This
1229 function assumes that the list isn't empty.
1230
1231 \sa last(), isEmpty(), constFirst()
1232*/
1233
1234/*! \fn template <typename T> const T& QList<T>::first() const
1235
1236 \overload
1237*/
1238
1239/*! \fn template <typename T> const T& QList<T>::constFirst() const
1240 \since 5.6
1241
1242 Returns a const reference to the first item in the list. This
1243 function assumes that the list isn't empty.
1244
1245 \sa constLast(), isEmpty(), first()
1246*/
1247
1248/*! \fn template <typename T> T& QList<T>::last()
1249
1250 Returns a reference to the last item in the list. This function
1251 assumes that the list isn't empty.
1252
1253 \sa first(), isEmpty(), constLast()
1254*/
1255
1256/*! \fn template <typename T> const T& QList<T>::last() const
1257
1258 \overload
1259*/
1260
1261/*! \fn template <typename T> const T& QList<T>::constLast() const
1262 \since 5.6
1263
1264 Returns a const reference to the last item in the list. This function
1265 assumes that the list isn't empty.
1266
1267 \sa constFirst(), isEmpty(), last()
1268*/
1269
1270/*! \fn template <typename T> T QList<T>::value(qsizetype i) const
1271
1272 Returns the value at index position \a i in the list.
1273
1274 If the index \a i is out of bounds, the function returns a
1275 \l{default-constructed value}. If you are certain that \a i is within
1276 bounds, you can use at() instead, which is slightly faster.
1277
1278 \sa at(), operator[]()
1279*/
1280
1281/*! \fn template <typename T> T QList<T>::value(qsizetype i, parameter_type defaultValue) const
1282
1283 \overload
1284
1285 If the index \a i is out of bounds, the function returns \a defaultValue.
1286*/
1287
1288/*! \fn template <typename T> void QList<T>::push_back(parameter_type value)
1289
1290 This function is provided for STL compatibility. It is equivalent
1291 to append(\a value).
1292*/
1293
1294/*! \fn template <typename T> void QList<T>::push_back(rvalue_ref value)
1295 \since 5.6
1296 \overload
1297*/
1298
1299/*!
1300 \fn template <typename T> void QList<T>::push_front(parameter_type value)
1301 \fn template <typename T> void QList<T>::push_front(rvalue_ref value)
1302
1303 This function is provided for STL compatibility. It is equivalent
1304 to prepend(\a value).
1305*/
1306
1307/*! \fn template <typename T> void QList<T>::pop_front()
1308
1309 This function is provided for STL compatibility. It is equivalent
1310 to removeFirst().
1311*/
1312
1313/*! \fn template <typename T> void QList<T>::pop_back()
1314
1315 This function is provided for STL compatibility. It is equivalent
1316 to removeLast().
1317*/
1318
1319/*! \fn template <typename T> T& QList<T>::front()
1320
1321 This function is provided for STL compatibility. It is equivalent
1322 to first().
1323*/
1324
1325/*! \fn template <typename T> QList<T>::const_reference QList<T>::front() const
1326
1327 \overload
1328*/
1329
1330/*! \fn template <typename T> QList<T>::reference QList<T>::back()
1331
1332 This function is provided for STL compatibility. It is equivalent
1333 to last().
1334*/
1335
1336/*! \fn template <typename T> QList<T>::const_reference QList<T>::back() const
1337
1338 \overload
1339*/
1340
1341/*! \fn template <typename T> void QList<T>::shrink_to_fit()
1342 \since 5.10
1343
1344 This function is provided for STL compatibility. It is equivalent
1345 to squeeze().
1346*/
1347
1348/*! \fn template <typename T> bool QList<T>::empty() const
1349
1350 This function is provided for STL compatibility. It is equivalent
1351 to isEmpty(), returning \c true if the list is empty; otherwise
1352 returns \c false.
1353*/
1354
1355/*! \fn template <typename T> qsizetype QList<T>::max_size() const
1356 \fn template <typename T> qsizetype QList<T>::maxSize()
1357 \since 6.8
1358
1359 It returns the maximum number of elements that the list can
1360 theoretically hold. In practice, the number can be much smaller,
1361 limited by the amount of memory available to the system.
1362*/
1363
1364/*! \fn template <typename T> QList<T> &QList<T>::operator+=(const QList<T> &other)
1365
1366 Appends the items of the \a other list to this list and
1367 returns a reference to this list.
1368
1369 \sa operator+(), append()
1370*/
1371
1372/*! \fn template <typename T> QList<T> &QList<T>::operator+=(QList<T> &&other)
1373 \since 6.0
1374
1375 \overload
1376
1377 \sa operator+(), append()
1378*/
1379
1380/*! \fn template <typename T> void QList<T>::operator+=(parameter_type value)
1381
1382 \overload
1383
1384 Appends \a value to the list.
1385
1386 \sa append(), operator<<()
1387*/
1388
1389/*! \fn template <typename T> void QList<T>::operator+=(rvalue_ref value)
1390 \since 5.11
1391
1392 \overload
1393
1394 \sa append(), operator<<()
1395*/
1396
1397/*!
1398 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const &
1399 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) &&
1400 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) const &
1401 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) &&
1402
1403 Returns a list that contains all the items in this list
1404 followed by all the items in the \a other list.
1405
1406 \sa operator+=()
1407*/
1408
1409/*! \fn template <typename T> QList<T> &QList<T>::operator<<(parameter_type value)
1410
1411 Appends \a value to the list and returns a reference to this list.
1412
1413 \sa append(), operator+=()
1414*/
1415
1416/*! \fn template <typename T> QList<T> &QList<T>::operator<<(rvalue_ref value)
1417 \since 5.11
1418
1419 \overload
1420
1421 \sa append(), operator+=()
1422*/
1423
1424
1425/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const QList<T> &other)
1426
1427 Appends \a other to the list and returns a reference to the list.
1428*/
1429
1430/*! \fn template <typename T> QList<T> &QList<T>::operator<<(QList<T> &&other)
1431 \since 6.0
1432
1433 \overload
1434*/
1435
1436/*! \class QList::iterator
1437 \inmodule QtCore
1438 \brief Provides an STL-style non-const iterator for QList and QStack.
1439
1440 QList provides both \l{STL-style iterators} and \l{Java-style
1441 iterators}.
1442
1443//! [iterator-invalidation-class-desc]
1444 \warning Iterators on implicitly shared containers do not work
1445 exactly like STL-iterators. You should avoid copying a container
1446 while iterators are active on that container. For more information,
1447 read \l{Implicit sharing iterator problem}.
1448
1449 \warning Iterators are invalidated when QList is modified. Consider that all
1450 iterators are invalidated by default. Exceptions to this rule are explicitly
1451 documented.
1452//! [iterator-invalidation-class-desc]
1453
1454 \sa QList::begin(), QList::end(), QList::const_iterator, QMutableListIterator
1455*/
1456
1457/*! \class QList::const_iterator
1458 \inmodule QtCore
1459 \brief Provides an STL-style const iterator for QList and QStack.
1460
1461 QList provides both \l{STL-style iterators} and \l{Java-style
1462 iterators}.
1463
1464 \include qlist.qdoc iterator-invalidation-class-desc
1465
1466 \sa QList::constBegin(), QList::constEnd(), QList::iterator, QListIterator
1467*/
1468
1469/*! \typedef QList::reverse_iterator
1470 \since 5.6
1471
1472 The QList::reverse_iterator typedef provides an STL-style non-const
1473 reverse iterator for QList.
1474
1475 \include qlist.qdoc iterator-invalidation-class-desc
1476
1477 \sa QList::rbegin(), QList::rend(), QList::const_reverse_iterator, QList::iterator
1478*/
1479
1480/*! \typedef QList::const_reverse_iterator
1481 \since 5.6
1482
1483 The QList::const_reverse_iterator typedef provides an STL-style const
1484 reverse iterator for QList.
1485
1486 \include qlist.qdoc iterator-invalidation-class-desc
1487
1488 \sa QList::rbegin(), QList::rend(), QList::reverse_iterator, QList::const_iterator
1489*/
1490
1491/*! \typedef QList::Iterator
1492
1493 Qt-style synonym for QList::iterator.
1494*/
1495
1496/*! \typedef QList::ConstIterator
1497
1498 Qt-style synonym for QList::const_iterator.
1499*/
1500
1501/*! \typedef QList::const_pointer
1502
1503 Provided for STL compatibility.
1504*/
1505
1506/*! \typedef QList::const_reference
1507
1508 Provided for STL compatibility.
1509*/
1510
1511/*! \typedef QList::difference_type
1512
1513 Provided for STL compatibility.
1514*/
1515
1516/*! \typedef QList::pointer
1517
1518 Provided for STL compatibility.
1519*/
1520
1521/*! \typedef QList::reference
1522
1523 Provided for STL compatibility.
1524*/
1525
1526/*! \typedef QList::size_type
1527
1528 Provided for STL compatibility.
1529*/
1530
1531/*! \typedef QList::value_type
1532
1533 Provided for STL compatibility.
1534*/
1535
1536/*! \typedef QList::parameter_type
1537
1538*/
1539
1540/*! \typedef QList::rvalue_ref
1541
1542*/
1543
1544/*! \fn template <typename T> QList<T> QList<T>::toList() const
1545 \fn template <typename T> QList<T> QList<T>::toVector() const
1546 \deprecated
1547
1548 A no-op in Qt 6. Provided for backwards compatibility with
1549 Qt 5, where QList and QVector where two different types.
1550
1551 Returns this list.
1552*/
1553
1554/*! \fn template <typename T> QList<T> QList<T>::fromList(const QList<T> &list)
1555 \fn template <typename T> QList<T> QList<T>::fromVector(const QList<T> &list)
1556 \deprecated
1557
1558 A no-op in Qt 6. Provided for backwards compatibility with
1559 Qt 5, where QList and QVector were two different types.
1560
1561 Returns this list.
1562*/
1563
1564/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list)
1565 \relates QList
1566
1567 Writes the list \a list to stream \a out.
1568
1569 This function requires the value type to implement \c operator<<().
1570
1571 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1572*/
1573
1574/*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list)
1575 \relates QList
1576
1577 Reads a list from stream \a in into \a list.
1578
1579 This function requires the value type to implement \c operator>>().
1580
1581 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1582*/
1583
1584/*! \fn template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t)
1585 \relates QList
1586 \since 6.1
1587
1588 Removes all elements that compare equal to \a t from the
1589 list \a list. Returns the number of elements removed, if any.
1590
1591 \note Unlike QList::removeAll, \a t is not allowed to be a
1592 reference to an element inside \a list. If you cannot be sure that
1593 this is not the case, take a copy of \a t and call this function
1594 with the copy.
1595
1596 \sa QList::removeAll(), erase_if
1597*/
1598
1599/*! \fn template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred)
1600 \relates QList
1601 \since 6.1
1602
1603 Removes all elements for which the predicate \a pred returns true
1604 from the list \a list. Returns the number of elements removed, if
1605 any.
1606
1607 \sa erase
1608*/
1609
1610/*! \fn template <typename T> QList<T>& QList<T>::assign(qsizetype n, parameter_type t)
1611 \since 6.6
1612
1613 Replaces the contents of this list with \a n copies of \a t.
1614
1615 The size of this list will be equal to \a n.
1616
1617 This function will only allocate memory if \a n exceeds the capacity of the
1618 list or this list is shared.
1619*/
1620
1621/*! \fn template <typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator>> QList<T>& QList<T>::assign(InputIterator first, InputIterator last)
1622 \since 6.6
1623
1624 Replaces the contents of this list with a copy of the elements in the
1625 iterator range [\a first, \a last).
1626
1627 The size of this list will be equal to the number of elements in the
1628 range [\a first, \a last).
1629
1630 This function will only allocate memory if the number of elements in the
1631 range exceeds the capacity of this list or this list is shared.
1632
1633 \note The behavior is undefined if either argument is an iterator into
1634 *this.
1635
1636 \constraints
1637 \c InputIterator meets the requirements of a
1638 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
1639*/
1640
1641/*! \fn template <typename T> QList<T>& QList<T>::assign(std::initializer_list<T> l)
1642 \since 6.6
1643
1644 Replaces the contents of this list with a copy of the elements of
1645 \a l.
1646
1647 The size of this list will be equal to the number of elements in
1648 \a l.
1649
1650 This function only allocates memory if the number of elements in \a l
1651 exceeds the capacity of this list or this list is shared.
1652*/
1653
1654/*!
1655 \fn template <typename T> QList<T>::DataPointer &QList<T>::data_ptr() &;
1656 \fn template <typename T> const QList<T>::DataPointer &QList<T>::data_ptr() const &;
1657 \fn template <typename T> QList<T>::DataPointer QList<T>::data_ptr() &&;
1658
1659 \internal
1660 \since 6.10
1661*/