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 \internal
554*/
555
556/*! \fn template <typename T> bool QList<T>::isDetached() const
557
558 \internal
559*/
560
561/*! \fn template <typename T> void QList<T>::setSharable(bool sharable)
562
563 \internal
564*/
565
566/*! \fn template <typename T> bool QList<T>::isSharedWith(const QList<T> &other) const
567
568 \internal
569*/
570
571/*! \fn template <typename T> T *QList<T>::data()
572
573 Returns a pointer to the data stored in the list. The pointer
574 can be used to access and modify the items in the list.
575
576 Example:
577 \snippet code/src_corelib_tools_qlist.cpp 6
578
579 \warning The pointer is invalidated on detachment or when the QList is
580 modified.
581
582 This function is mostly useful to pass a list to a function
583 that accepts a plain C++ array.
584
585 \sa constData(), operator[]()
586*/
587
588/*! \fn template <typename T> const T *QList<T>::data() const
589
590 \overload
591*/
592
593/*! \fn template <typename T> const T *QList<T>::constData() const
594
595 Returns a const pointer to the data stored in the list. The
596 pointer can be used to access the items in the list.
597
598 \warning The pointer is invalidated on detachment or when the QList is
599 modified.
600
601 This function is mostly useful to pass a list to a function
602 that accepts a plain C++ array.
603
604 \sa data(), operator[]()
605*/
606
607/*! \fn template <typename T> void QList<T>::clear()
608
609 Removes all the elements from the list.
610
611 If this list is not shared, the capacity() is preserved. Use squeeze() to
612 shed excess capacity.
613
614 \note In Qt versions prior to 5.7 (for QVector) and 6.0 (for QList), this
615 function released the memory used by the list instead of preserving the
616 capacity.
617
618 \sa resize(), squeeze()
619*/
620
621/*! \fn template <typename T> const T &QList<T>::at(qsizetype i) const
622
623 Returns the item at index position \a i in the list.
624
625 \a i must be a valid index position in the list (i.e., 0 <= \a
626 i < size()).
627
628 \sa value(), operator[]()
629*/
630
631/*! \fn template <typename T> T &QList<T>::operator[](qsizetype i)
632
633 Returns the item at index position \a i as a modifiable reference.
634
635 \a i must be a valid index position in the list (i.e., 0 <= \a i
636 < size()).
637
638 Note that using non-const operators can cause QList to do a deep
639 copy.
640
641 \sa at(), value()
642*/
643
644/*! \fn template <typename T> const T &QList<T>::operator[](qsizetype i) const
645
646 \overload
647
648 Same as at(\a i).
649*/
650
651/*!
652 \fn template <typename T> void QList<T>::append(parameter_type value)
653
654 Inserts \a value at the end of the list.
655
656 Example:
657 \snippet code/src_corelib_tools_qlist.cpp 7
658
659 This is the same as calling resize(size() + 1) and assigning \a
660 value to the new last element in the list.
661
662 This operation is relatively fast, because QList typically
663 allocates more memory than necessary, so it can grow without
664 reallocating the entire list each time.
665
666 \sa operator<<(), prepend(), insert()
667*/
668
669/*!
670 \fn template <typename T> void QList<T>::append(rvalue_ref value)
671 \since 5.6
672
673 \overload
674
675 Example:
676 \snippet code/src_corelib_tools_qlist.cpp move-append
677*/
678
679/*! \fn template <typename T> void QList<T>::append(const QList<T> &value)
680
681 \overload
682
683 \since 5.5
684
685 Appends the items of the \a value list to this list.
686
687 \sa operator<<(), operator+=()
688*/
689
690/*! \fn template <typename T> void QList<T>::append(QList<T> &&value)
691 \overload
692
693 \since 6.0
694
695 Moves the items of the \a value list to the end of this list.
696
697 \sa operator<<(), operator+=()
698*/
699
700/*!
701 \fn template <typename T> void QList<T>::prepend(parameter_type value)
702 \fn template <typename T> void QList<T>::prepend(rvalue_ref value)
703
704 Inserts \a value at the beginning of the list.
705
706 Example:
707 \snippet code/src_corelib_tools_qlist.cpp 8
708
709 This is the same as list.insert(0, \a value).
710
711 Normally this operation is relatively fast (amortized \l{constant time}).
712 QList is able to allocate extra memory at the beginning of the list data
713 and grow in that direction without reallocating or moving the data on each
714 operation. However if you want a container class with a guarantee of
715 \l{constant time} prepend, use std::list instead,
716 but prefer QList otherwise.
717
718 \sa append(), insert()
719*/
720
721/*!
722 \fn template <typename T> template <typename ...Args> T &QList<T>::emplaceBack(Args&&... args)
723 \fn template <typename T> template <typename ...Args> T &QList<T>::emplace_back(Args&&... args)
724
725 Adds a new element to the end for the container. This new element
726 is constructed in-place using \a args as the arguments for its
727 construction.
728
729 Returns a reference to the new element.
730
731 Example:
732 \snippet code/src_corelib_tools_qlist.cpp emplace-back
733
734 It is also possible to access a newly created object by using
735 returned reference:
736 \snippet code/src_corelib_tools_qlist.cpp emplace-back-ref
737
738 This is the same as list.emplace(list.size(), \a args).
739
740 \sa emplace
741*/
742
743/*! \fn template <typename T> void QList<T>::insert(qsizetype i, parameter_type value)
744 \fn template <typename T> void QList<T>::insert(qsizetype i, rvalue_ref value)
745
746 Inserts \a value at index position \a i in the list. If \a i is
747 0, the value is prepended to the list. If \a i is size(), the
748 value is appended to the list.
749
750 Example:
751 \snippet code/src_corelib_tools_qlist.cpp 9
752
753 For large lists, this operation can be slow (\l{linear time}),
754 because it requires moving all the items at indexes \a i and
755 above by one position further in memory. If you want a container
756 class that provides a fast insert() function, use std::list
757 instead.
758
759 \sa append(), prepend(), remove()
760*/
761
762/*! \fn template <typename T> void QList<T>::insert(qsizetype i, qsizetype count, parameter_type value)
763
764 \overload
765
766 Inserts \a count copies of \a value at index position \a i in the
767 list.
768
769 Example:
770 \snippet code/src_corelib_tools_qlist.cpp 10
771*/
772
773/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, parameter_type value)
774 \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, rvalue_ref value)
775
776 \overload
777
778 Inserts \a value in front of the item pointed to by the iterator
779 \a before. Returns an iterator pointing at the inserted item.
780*/
781
782/*! \fn template <typename T> QList<T>::iterator QList<T>::insert(const_iterator before, qsizetype count, parameter_type value)
783
784 Inserts \a count copies of \a value in front of the item pointed to
785 by the iterator \a before. Returns an iterator pointing at the
786 first of the inserted items.
787*/
788
789/*!
790 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(qsizetype i, Args&&... args)
791
792 Extends the container by inserting a new element at position \a i.
793 This new element is constructed in-place using \a args as the
794 arguments for its construction.
795
796 Returns an iterator to the new element.
797
798 Example:
799 \snippet code/src_corelib_tools_qlist.cpp emplace
800
801 \note It is guaranteed that the element will be created in place
802 at the beginning, but after that it might be copied or
803 moved to the right position.
804
805 \sa emplaceBack
806*/
807
808
809/*! \fn template <typename T> void QList<T>::replace(qsizetype i, parameter_type value)
810 \fn template <typename T> void QList<T>::replace(qsizetype i, rvalue_ref value)
811
812 Replaces the item at index position \a i with \a value.
813
814 \a i must be a valid index position in the list (i.e., 0 <= \a
815 i < size()).
816
817 \sa operator[](), remove()
818*/
819
820/*! \fn template <typename T> void QList<T>::remove(qsizetype i, qsizetype n = 1)
821
822 Removes \a n elements from the list, starting at index position \a i.
823
824//! [shrinking-erase]
825 Element removal will preserve the list's capacity and not reduce the amount of
826 allocated memory. To shed extra capacity and free as much memory as possible,
827 call squeeze().
828//! [shrinking-erase]
829
830//! [iterator-invalidation-erase]
831 \note When QList is not \l{implicitly shared}, this function only
832 invalidates iterators at or after the specified position.
833//! [iterator-invalidation-erase]
834
835 \sa insert(), replace(), fill()
836*/
837
838/*! \fn template <typename T> void QList<T>::removeAt(qsizetype i)
839 \since 5.2
840
841 Removes the element at index position \a i.
842 Equivalent to
843 \code
844 remove(i);
845 \endcode
846
847 \include qlist.qdoc shrinking-erase
848 \include qlist.qdoc iterator-invalidation-erase
849
850 \sa remove()
851*/
852
853/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::removeAll(const AT &t)
854 \since 5.4
855
856 Removes all elements that compare equal to \a t from the
857 list. Returns the number of elements removed, if any.
858
859 \include qlist.qdoc shrinking-erase
860
861 \sa removeOne()
862*/
863
864/*! \fn template <typename T> template <typename AT = T> bool QList<T>::removeOne(const AT &t)
865 \since 5.4
866
867 Removes the first element that compares equal to \a t from the
868 list. Returns whether an element was, in fact, removed.
869
870 \include qlist.qdoc shrinking-erase
871
872 \sa removeAll()
873*/
874
875/*! \fn template <typename T> template <typename Predicate> qsizetype QList<T>::removeIf(Predicate pred)
876 \since 6.1
877
878 Removes all elements for which the predicate \a pred returns true
879 from the list. Returns the number of elements removed, if any.
880
881 \sa removeAll()
882*/
883
884/*! \fn template <typename T> qsizetype QList<T>::length() const
885 \since 5.2
886
887 Same as size() and count().
888
889 \sa size(), count()
890*/
891
892/*! \fn template <typename T> T QList<T>::takeAt(qsizetype i)
893 \since 5.2
894
895 Removes the element at index position \a i and returns it.
896
897 Equivalent to
898 \code
899 T t = at(i);
900 remove(i);
901 return t;
902 \endcode
903
904 \include qlist.qdoc iterator-invalidation-erase
905
906 \sa takeFirst(), takeLast()
907*/
908
909/*! \fn template <typename T> void QList<T>::move(qsizetype from, qsizetype to)
910 \since 5.6
911
912 Moves the item at index position \a from to index position \a to.
913
914 \c from and \c to must be within bounds.
915
916 For example, to move the first item to the end of the list:
917 \code
918 QList<int> list = {1, 2, 3};
919 list.move(0, list.size() - 1);
920 qDebug() << list; // Prints "QList(2, 3, 1)"
921 \endcode
922*/
923
924/*! \fn template <typename T> void QList<T>::removeFirst()
925 \since 5.1
926 Removes the first item in the list. Calling this function is
927 equivalent to calling remove(0). The list must not be empty. If
928 the list can be empty, call isEmpty() before calling this
929 function.
930
931 \include qlist.qdoc shrinking-erase
932
933 \sa remove(), takeFirst(), isEmpty()
934*/
935
936/*! \fn template <typename T> void QList<T>::removeLast()
937 \since 5.1
938 Removes the last item in the list. Calling this function is
939 equivalent to calling remove(size() - 1). The list must not be
940 empty. If the list can be empty, call isEmpty() before calling
941 this function.
942
943 \include qlist.qdoc shrinking-erase
944
945 \sa remove(), takeLast(), removeFirst(), isEmpty()
946*/
947
948/*! \fn template <typename T> T QList<T>::takeFirst()
949 \since 5.1
950
951 Removes the first item in the list and returns it. This function
952 assumes the list is not empty. To avoid failure, call isEmpty()
953 before calling this function.
954
955 \sa takeLast(), removeFirst()
956*/
957
958/*! \fn template <typename T> T QList<T>::takeLast()
959 \since 5.1
960
961 Removes the last item in the list and returns it. This function
962 assumes the list is not empty. To avoid failure, call isEmpty()
963 before calling this function.
964
965 If you don't use the return value, removeLast() is more
966 efficient.
967
968 \sa takeFirst(), removeLast()
969*/
970
971/*!
972 \fn template <typename T> template <typename ...Args> QList<T>::iterator QList<T>::emplace(const_iterator before, Args&&... args)
973
974 \overload
975
976 Creates a new element in front of the item pointed to by the
977 iterator \a before. This new element is constructed in-place
978 using \a args as the arguments for its construction.
979
980 Returns an iterator to the new element.
981*/
982
983/*! \fn template <typename T> QList<T> &QList<T>::fill(parameter_type value, qsizetype size = -1)
984
985 Assigns \a value to all items in the list. If \a size is
986 different from -1 (the default), the list is resized to \a size beforehand.
987
988 Example:
989 \snippet code/src_corelib_tools_qlist.cpp 11
990
991 \sa resize()
992*/
993
994/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::indexOf(const AT &value, qsizetype from = 0) const
995
996 Returns the index position of the first occurrence of \a value in
997 the list, searching forward from index position \a from.
998 Returns -1 if no item matched.
999
1000 Example:
1001 \snippet code/src_corelib_tools_qlist.cpp 12
1002
1003 This function requires the value type to have an implementation of
1004 \c operator==().
1005
1006 \sa lastIndexOf(), contains()
1007*/
1008
1009/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::lastIndexOf(const AT &value, qsizetype from = -1) const
1010
1011 Returns the index position of the last occurrence of the value \a
1012 value in the list, searching backward from index position \a
1013 from. If \a from is -1 (the default), the search starts at the
1014 last item. Returns -1 if no item matched.
1015
1016 Example:
1017 \snippet code/src_corelib_tools_qlist.cpp 13
1018
1019 This function requires the value type to have an implementation of
1020 \c operator==().
1021
1022 \sa indexOf()
1023*/
1024
1025/*! \fn template <typename T> template <typename AT = T> bool QList<T>::contains(const AT &value) const
1026
1027 Returns \c true if the list contains an occurrence of \a value;
1028 otherwise returns \c false.
1029
1030 This function requires the value type to have an implementation of
1031 \c operator==().
1032
1033 \sa indexOf(), count()
1034*/
1035
1036/*! \fn template <typename T> bool QList<T>::startsWith(parameter_type value) const
1037 \since 4.5
1038
1039 Returns \c true if this list is not empty and its first
1040 item is equal to \a value; otherwise returns \c false.
1041
1042 \sa isEmpty(), first()
1043*/
1044
1045/*! \fn template <typename T> bool QList<T>::endsWith(parameter_type value) const
1046 \since 4.5
1047
1048 Returns \c true if this list is not empty and its last
1049 item is equal to \a value; otherwise returns \c false.
1050
1051 \sa isEmpty(), last()
1052*/
1053
1054
1055/*! \fn template <typename T> template <typename AT = T> qsizetype QList<T>::count(const AT &value) const
1056
1057 Returns the number of occurrences of \a value in the list.
1058
1059 This function requires the value type to have an implementation of
1060 \c operator==().
1061
1062 \sa contains(), indexOf()
1063*/
1064
1065/*! \fn template <typename T> qsizetype QList<T>::count() const
1066
1067 \overload
1068
1069 Same as size().
1070*/
1071
1072/*! \fn template <typename T> QList<T>::iterator QList<T>::begin()
1073
1074 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the
1075 first item in the list.
1076
1077//! [iterator-invalidation-func-desc]
1078 \warning The returned iterator is invalidated on detachment or when the
1079 QList is modified.
1080//! [iterator-invalidation-func-desc]
1081
1082 \sa constBegin(), end()
1083*/
1084
1085/*! \fn template <typename T> QList<T>::const_iterator QList<T>::begin() const
1086
1087 \overload
1088*/
1089
1090/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cbegin() const
1091 \since 5.0
1092
1093 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1094 first item in the list.
1095
1096 \include qlist.qdoc iterator-invalidation-func-desc
1097
1098 \sa begin(), cend()
1099*/
1100
1101/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constBegin() const
1102
1103 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the
1104 first item in the list.
1105
1106 \include qlist.qdoc iterator-invalidation-func-desc
1107
1108 \sa begin(), constEnd()
1109*/
1110
1111/*! \fn template <typename T> QList<T>::iterator QList<T>::end()
1112
1113 Returns an \l{STL-style iterators}{STL-style iterator} pointing just after
1114 the last item in the list.
1115
1116 \include qlist.qdoc iterator-invalidation-func-desc
1117
1118 \sa begin(), constEnd()
1119*/
1120
1121/*! \fn template <typename T> QList<T>::const_iterator QList<T>::end() const
1122
1123 \overload
1124*/
1125
1126/*! \fn template <typename T> QList<T>::const_iterator QList<T>::cend() const
1127 \since 5.0
1128
1129 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1130 after the last item in the list.
1131
1132 \include qlist.qdoc iterator-invalidation-func-desc
1133
1134 \sa cbegin(), end()
1135*/
1136
1137/*! \fn template <typename T> QList<T>::const_iterator QList<T>::constEnd() const
1138
1139 Returns a const \l{STL-style iterators}{STL-style iterator} pointing just
1140 after the last item in the list.
1141
1142 \include qlist.qdoc iterator-invalidation-func-desc
1143
1144 \sa constBegin(), end()
1145*/
1146
1147/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rbegin()
1148 \since 5.6
1149
1150 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to
1151 the first item in the list, in reverse order.
1152
1153 \include qlist.qdoc iterator-invalidation-func-desc
1154
1155 \sa begin(), crbegin(), rend()
1156*/
1157
1158/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rbegin() const
1159 \since 5.6
1160 \overload
1161*/
1162
1163/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crbegin() const
1164 \since 5.6
1165
1166 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1167 to the first item in the list, in reverse order.
1168
1169 \include qlist.qdoc iterator-invalidation-func-desc
1170
1171 \sa begin(), rbegin(), rend()
1172*/
1173
1174/*! \fn template <typename T> QList<T>::reverse_iterator QList<T>::rend()
1175 \since 5.6
1176
1177 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing just
1178 after the last item in the list, in reverse order.
1179
1180 \include qlist.qdoc iterator-invalidation-func-desc
1181
1182 \sa end(), crend(), rbegin()
1183*/
1184
1185/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::rend() const
1186 \since 5.6
1187 \overload
1188*/
1189
1190/*! \fn template <typename T> QList<T>::const_reverse_iterator QList<T>::crend() const
1191 \since 5.6
1192
1193 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing
1194 just after the last item in the list, in reverse order.
1195
1196 \include qlist.qdoc iterator-invalidation-func-desc
1197
1198 \sa end(), rend(), rbegin()
1199*/
1200
1201/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator pos)
1202
1203 Removes the item pointed to by the iterator \a pos from the
1204 list, and returns an iterator to the next item in the list
1205 (which may be end()).
1206
1207 \include qlist.qdoc shrinking-erase
1208 \include qlist.qdoc iterator-invalidation-erase
1209
1210 \sa insert(), remove()
1211*/
1212
1213/*! \fn template <typename T> QList<T>::iterator QList<T>::erase(const_iterator begin, const_iterator end)
1214
1215 \overload
1216
1217 Removes all the items from \a begin up to (but not including) \a
1218 end. Returns an iterator to the same item that \a end referred to
1219 before the call.
1220
1221 \include qlist.qdoc shrinking-erase
1222 \include qlist.qdoc iterator-invalidation-erase
1223*/
1224
1225/*! \fn template <typename T> T& QList<T>::first()
1226
1227 Returns a reference to the first item in the list. This
1228 function assumes that the list isn't empty.
1229
1230 \sa last(), isEmpty(), constFirst()
1231*/
1232
1233/*! \fn template <typename T> const T& QList<T>::first() const
1234
1235 \overload
1236*/
1237
1238/*! \fn template <typename T> const T& QList<T>::constFirst() const
1239 \since 5.6
1240
1241 Returns a const reference to the first item in the list. This
1242 function assumes that the list isn't empty.
1243
1244 \sa constLast(), isEmpty(), first()
1245*/
1246
1247/*! \fn template <typename T> T& QList<T>::last()
1248
1249 Returns a reference to the last item in the list. This function
1250 assumes that the list isn't empty.
1251
1252 \sa first(), isEmpty(), constLast()
1253*/
1254
1255/*! \fn template <typename T> const T& QList<T>::last() const
1256
1257 \overload
1258*/
1259
1260/*! \fn template <typename T> const T& QList<T>::constLast() const
1261 \since 5.6
1262
1263 Returns a const reference to the last item in the list. This function
1264 assumes that the list isn't empty.
1265
1266 \sa constFirst(), isEmpty(), last()
1267*/
1268
1269/*! \fn template <typename T> T QList<T>::value(qsizetype i) const
1270
1271 Returns the value at index position \a i in the list.
1272
1273 If the index \a i is out of bounds, the function returns a
1274 \l{default-constructed value}. If you are certain that \a i is within
1275 bounds, you can use at() instead, which is slightly faster.
1276
1277 \sa at(), operator[]()
1278*/
1279
1280/*! \fn template <typename T> T QList<T>::value(qsizetype i, parameter_type defaultValue) const
1281
1282 \overload
1283
1284 If the index \a i is out of bounds, the function returns \a defaultValue.
1285*/
1286
1287/*! \fn template <typename T> void QList<T>::push_back(parameter_type value)
1288
1289 This function is provided for STL compatibility. It is equivalent
1290 to append(\a value).
1291*/
1292
1293/*! \fn template <typename T> void QList<T>::push_back(rvalue_ref value)
1294 \since 5.6
1295 \overload
1296*/
1297
1298/*!
1299 \fn template <typename T> void QList<T>::push_front(parameter_type value)
1300 \fn template <typename T> void QList<T>::push_front(rvalue_ref value)
1301
1302 This function is provided for STL compatibility. It is equivalent
1303 to prepend(\a value).
1304*/
1305
1306/*! \fn template <typename T> void QList<T>::pop_front()
1307
1308 This function is provided for STL compatibility. It is equivalent
1309 to removeFirst().
1310*/
1311
1312/*! \fn template <typename T> void QList<T>::pop_back()
1313
1314 This function is provided for STL compatibility. It is equivalent
1315 to removeLast().
1316*/
1317
1318/*! \fn template <typename T> T& QList<T>::front()
1319
1320 This function is provided for STL compatibility. It is equivalent
1321 to first().
1322*/
1323
1324/*! \fn template <typename T> QList<T>::const_reference QList<T>::front() const
1325
1326 \overload
1327*/
1328
1329/*! \fn template <typename T> QList<T>::reference QList<T>::back()
1330
1331 This function is provided for STL compatibility. It is equivalent
1332 to last().
1333*/
1334
1335/*! \fn template <typename T> QList<T>::const_reference QList<T>::back() const
1336
1337 \overload
1338*/
1339
1340/*! \fn template <typename T> void QList<T>::shrink_to_fit()
1341 \since 5.10
1342
1343 This function is provided for STL compatibility. It is equivalent
1344 to squeeze().
1345*/
1346
1347/*! \fn template <typename T> bool QList<T>::empty() const
1348
1349 This function is provided for STL compatibility. It is equivalent
1350 to isEmpty(), returning \c true if the list is empty; otherwise
1351 returns \c false.
1352*/
1353
1354/*! \fn template <typename T> qsizetype QList<T>::max_size() const
1355 \fn template <typename T> qsizetype QList<T>::maxSize()
1356 \since 6.8
1357
1358 It returns the maximum number of elements that the list can
1359 theoretically hold. In practice, the number can be much smaller,
1360 limited by the amount of memory available to the system.
1361*/
1362
1363/*! \fn template <typename T> QList<T> &QList<T>::operator+=(const QList<T> &other)
1364
1365 Appends the items of the \a other list to this list and
1366 returns a reference to this list.
1367
1368 \sa operator+(), append()
1369*/
1370
1371/*! \fn template <typename T> QList<T> &QList<T>::operator+=(QList<T> &&other)
1372 \since 6.0
1373
1374 \overload
1375
1376 \sa operator+(), append()
1377*/
1378
1379/*! \fn template <typename T> void QList<T>::operator+=(parameter_type value)
1380
1381 \overload
1382
1383 Appends \a value to the list.
1384
1385 \sa append(), operator<<()
1386*/
1387
1388/*! \fn template <typename T> void QList<T>::operator+=(rvalue_ref value)
1389 \since 5.11
1390
1391 \overload
1392
1393 \sa append(), operator<<()
1394*/
1395
1396/*!
1397 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) const &
1398 \fn template <typename T> QList<T> QList<T>::operator+(const QList<T> &other) &&
1399 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) const &
1400 \fn template <typename T> QList<T> QList<T>::operator+(QList<T> &&other) &&
1401
1402 Returns a list that contains all the items in this list
1403 followed by all the items in the \a other list.
1404
1405 \sa operator+=()
1406*/
1407
1408/*! \fn template <typename T> QList<T> &QList<T>::operator<<(parameter_type value)
1409
1410 Appends \a value to the list and returns a reference to this list.
1411
1412 \sa append(), operator+=()
1413*/
1414
1415/*! \fn template <typename T> QList<T> &QList<T>::operator<<(rvalue_ref value)
1416 \since 5.11
1417
1418 \overload
1419
1420 \sa append(), operator+=()
1421*/
1422
1423
1424/*! \fn template <typename T> QList<T> &QList<T>::operator<<(const QList<T> &other)
1425
1426 Appends \a other to the list and returns a reference to the list.
1427*/
1428
1429/*! \fn template <typename T> QList<T> &QList<T>::operator<<(QList<T> &&other)
1430 \since 6.0
1431
1432 \overload
1433*/
1434
1435/*! \class QList::iterator
1436 \inmodule QtCore
1437 \brief Provides an STL-style non-const iterator for QList and QStack.
1438
1439 QList provides both \l{STL-style iterators} and \l{Java-style
1440 iterators}.
1441
1442//! [iterator-invalidation-class-desc]
1443 \warning Iterators on implicitly shared containers do not work
1444 exactly like STL-iterators. You should avoid copying a container
1445 while iterators are active on that container. For more information,
1446 read \l{Implicit sharing iterator problem}.
1447
1448 \warning Iterators are invalidated when QList is modified. Consider that all
1449 iterators are invalidated by default. Exceptions to this rule are explicitly
1450 documented.
1451//! [iterator-invalidation-class-desc]
1452
1453 \sa QList::begin(), QList::end(), QList::const_iterator, QMutableListIterator
1454*/
1455
1456/*! \class QList::const_iterator
1457 \inmodule QtCore
1458 \brief Provides an STL-style const iterator for QList and QStack.
1459
1460 QList provides both \l{STL-style iterators} and \l{Java-style
1461 iterators}.
1462
1463 \include qlist.qdoc iterator-invalidation-class-desc
1464
1465 \sa QList::constBegin(), QList::constEnd(), QList::iterator, QListIterator
1466*/
1467
1468/*! \typedef QList::reverse_iterator
1469 \since 5.6
1470
1471 The QList::reverse_iterator typedef provides an STL-style non-const
1472 reverse iterator for QList.
1473
1474 \include qlist.qdoc iterator-invalidation-class-desc
1475
1476 \sa QList::rbegin(), QList::rend(), QList::const_reverse_iterator, QList::iterator
1477*/
1478
1479/*! \typedef QList::const_reverse_iterator
1480 \since 5.6
1481
1482 The QList::const_reverse_iterator typedef provides an STL-style const
1483 reverse iterator for QList.
1484
1485 \include qlist.qdoc iterator-invalidation-class-desc
1486
1487 \sa QList::rbegin(), QList::rend(), QList::reverse_iterator, QList::const_iterator
1488*/
1489
1490/*! \typedef QList::Iterator
1491
1492 Qt-style synonym for QList::iterator.
1493*/
1494
1495/*! \typedef QList::ConstIterator
1496
1497 Qt-style synonym for QList::const_iterator.
1498*/
1499
1500/*! \typedef QList::const_pointer
1501
1502 Provided for STL compatibility.
1503*/
1504
1505/*! \typedef QList::const_reference
1506
1507 Provided for STL compatibility.
1508*/
1509
1510/*! \typedef QList::difference_type
1511
1512 Provided for STL compatibility.
1513*/
1514
1515/*! \typedef QList::pointer
1516
1517 Provided for STL compatibility.
1518*/
1519
1520/*! \typedef QList::reference
1521
1522 Provided for STL compatibility.
1523*/
1524
1525/*! \typedef QList::size_type
1526
1527 Provided for STL compatibility.
1528*/
1529
1530/*! \typedef QList::value_type
1531
1532 Provided for STL compatibility.
1533*/
1534
1535/*! \typedef QList::parameter_type
1536
1537*/
1538
1539/*! \typedef QList::rvalue_ref
1540
1541*/
1542
1543/*! \fn template <typename T> QList<T> QList<T>::toList() const
1544 \fn template <typename T> QList<T> QList<T>::toVector() const
1545 \deprecated
1546
1547 A no-op in Qt 6. Provided for backwards compatibility with
1548 Qt 5, where QList and QVector where two different types.
1549
1550 Returns this list.
1551*/
1552
1553/*! \fn template <typename T> QList<T> QList<T>::fromList(const QList<T> &list)
1554 \fn template <typename T> QList<T> QList<T>::fromVector(const QList<T> &list)
1555 \deprecated
1556
1557 A no-op in Qt 6. Provided for backwards compatibility with
1558 Qt 5, where QList and QVector were two different types.
1559
1560 Returns this list.
1561*/
1562
1563/*! \fn template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list)
1564 \relates QList
1565
1566 Writes the list \a list to stream \a out.
1567
1568 This function requires the value type to implement \c operator<<().
1569
1570 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1571*/
1572
1573/*! \fn template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list)
1574 \relates QList
1575
1576 Reads a list from stream \a in into \a list.
1577
1578 This function requires the value type to implement \c operator>>().
1579
1580 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1581*/
1582
1583/*! \fn template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t)
1584 \relates QList
1585 \since 6.1
1586
1587 Removes all elements that compare equal to \a t from the
1588 list \a list. Returns the number of elements removed, if any.
1589
1590 \note Unlike QList::removeAll, \a t is not allowed to be a
1591 reference to an element inside \a list. If you cannot be sure that
1592 this is not the case, take a copy of \a t and call this function
1593 with the copy.
1594
1595 \sa QList::removeAll(), erase_if
1596*/
1597
1598/*! \fn template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred)
1599 \relates QList
1600 \since 6.1
1601
1602 Removes all elements for which the predicate \a pred returns true
1603 from the list \a list. Returns the number of elements removed, if
1604 any.
1605
1606 \sa erase
1607*/
1608
1609/*! \fn template <typename T> QList<T>& QList<T>::assign(qsizetype n, parameter_type t)
1610 \since 6.6
1611
1612 Replaces the contents of this list with \a n copies of \a t.
1613
1614 The size of this list will be equal to \a n.
1615
1616 This function will only allocate memory if \a n exceeds the capacity of the
1617 list or this list is shared.
1618*/
1619
1620/*! \fn template <typename T> template <typename InputIterator, QList<T>::if_input_iterator<InputIterator>> QList<T>& QList<T>::assign(InputIterator first, InputIterator last)
1621 \since 6.6
1622
1623 Replaces the contents of this list with a copy of the elements in the
1624 iterator range [\a first, \a last).
1625
1626 The size of this list will be equal to the number of elements in the
1627 range [\a first, \a last).
1628
1629 This function will only allocate memory if the number of elements in the
1630 range exceeds the capacity of this list or this list is shared.
1631
1632 \note The behavior is undefined if either argument is an iterator into
1633 *this.
1634
1635 \constraints
1636 \c InputIterator meets the requirements of a
1637 \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}.
1638*/
1639
1640/*! \fn template <typename T> QList<T>& QList<T>::assign(std::initializer_list<T> l)
1641 \since 6.6
1642
1643 Replaces the contents of this list with a copy of the elements of
1644 \a l.
1645
1646 The size of this list will be equal to the number of elements in
1647 \a l.
1648
1649 This function only allocates memory if the number of elements in \a l
1650 exceeds the capacity of this list or this list is shared.
1651*/
1652
1653/*!
1654 \fn template <typename T> QList<T>::DataPointer &QList<T>::data_ptr() &;
1655 \fn template <typename T> const QList<T>::DataPointer &QList<T>::data_ptr() const &;
1656 \fn template <typename T> QList<T>::DataPointer QList<T>::data_ptr() &&;
1657
1658 \internal
1659 \since 6.10
1660*/