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