1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#ifdef QT_NO_LINKED_LIST
41# undef QT_NO_LINKED_LIST
42#endif
43
44#include "qlinkedlist.h"
45
46QT_BEGIN_NAMESPACE
47
48#if QT_DEPRECATED_SINCE(5, 15)
49
50QT_WARNING_PUSH
51QT_WARNING_DISABLE_DEPRECATED
52
53const QLinkedListData QLinkedListData::shared_null = {
54 .n: const_cast<QLinkedListData *>(&QLinkedListData::shared_null),
55 .p: const_cast<QLinkedListData *>(&QLinkedListData::shared_null),
56 Q_REFCOUNT_INITIALIZE_STATIC, .size: 0, .sharable: true
57};
58
59/*! \class QLinkedList
60 \inmodule QtCore
61 \obsolete
62 \brief The QLinkedList class is a template class that provides linked lists.
63
64 \ingroup tools
65 \ingroup shared
66
67 \reentrant
68
69 \note This class is obsolete, please use std::list instead.
70
71 QLinkedList\<T\> is one of Qt's generic \l{container classes}. It
72 stores a list of values and provides iterator-based access as
73 well as \l{constant time} insertions and removals.
74
75 QList\<T\>, QLinkedList\<T\>, and QVector\<T\> provide similar
76 functionality. Here's an overview:
77
78 \list
79 \li For most purposes, QList is the right class to use. Its
80 index-based API is more convenient than QLinkedList's
81 iterator-based API, and it is usually faster than
82 QVector because of the way it stores its items in
83 memory (see \l{Algorithmic Complexity} for details).
84 It also expands to less code in your executable.
85 \li If you need a real linked list, with guarantees of \l{constant
86 time} insertions in the middle of the list and iterators to
87 items rather than indexes, use QLinkedList.
88 \li If you want the items to occupy adjacent memory positions,
89 use QVector.
90 \endlist
91
92 Here's an example of a QLinkedList that stores integers and a
93 QLinkedList that stores QTime values:
94
95 \snippet code/src_corelib_tools_qlinkedlist.cpp 0
96
97 QLinkedList stores a list of items. The default constructor
98 creates an empty list. To insert items into the list, you can use
99 operator<<():
100
101 \snippet code/src_corelib_tools_qlinkedlist.cpp 1
102
103 If you want to get the first or last item in a linked list, use
104 first() or last(). If you want to remove an item from either end
105 of the list, use removeFirst() or removeLast(). If you want to
106 remove all occurrences of a given value in the list, use
107 removeAll().
108
109 A common requirement is to remove the first or last item in the
110 list and do something with it. For this, QLinkedList provides
111 takeFirst() and takeLast(). Here's a loop that removes the items
112 from a list one at a time and calls \c delete on them:
113 \snippet code/src_corelib_tools_qlinkedlist.cpp 2
114
115 QLinkedList's value type must be an \l {assignable data type}. This
116 covers most data types that are commonly used, but the compiler
117 won't let you, for example, store a QWidget as a value; instead,
118 store a QWidget *. A few functions have additional requirements;
119 for example, contains() and removeAll() expect the value type to
120 support \c operator==(). These requirements are documented on a
121 per-function basis.
122
123 If you want to insert, modify, or remove items in the middle of
124 the list, you must use an iterator. QLinkedList provides both
125 \l{Java-style iterators} (QLinkedListIterator and
126 QMutableLinkedListIterator) and \l{STL-style iterators}
127 (QLinkedList::const_iterator and QLinkedList::iterator). See the
128 documentation for these classes for details.
129
130 \sa QLinkedListIterator, QMutableLinkedListIterator, QList, QVector
131*/
132
133/*! \fn template <class T> QLinkedList<T>::QLinkedList()
134
135 Constructs an empty list.
136*/
137
138/*!
139 \fn template <class T> QLinkedList<T>::QLinkedList(QLinkedList<T> &&other)
140
141 Move-constructs a QLinkedList instance, making it point at the same
142 object that \a other was pointing to.
143
144 \since 5.2
145*/
146
147/*! \fn template <class T> QLinkedList<T>::QLinkedList(const QLinkedList<T> &other)
148
149 Constructs a copy of \a other.
150
151 This operation occurs in \l{constant time}, because QLinkedList
152 is \l{implicitly shared}. This makes returning a QLinkedList from
153 a function very fast. If a shared instance is modified, it will
154 be copied (copy-on-write), and this takes \l{linear time}.
155
156 \sa operator=()
157*/
158
159/*! \fn template <class T> QLinkedList<T>::QLinkedList(std::initializer_list<T> list)
160 \since 5.2
161
162 Constructs a list from the std::initializer_list specified by \a list.
163
164 This constructor is only enabled if the compiler supports C++11
165 initializer lists.
166*/
167
168/*! \fn template <class T> template<typename InputIterator> QLinkedList<T>::QLinkedList(InputIterator first, InputIterator last)
169 \since 5.14
170
171 Constructs a list with the contents in the iterator range [\a first, \a last).
172
173 The value type of \c InputIterator must be convertible to \c T.
174*/
175
176/*! \fn template <class T> QLinkedList<T>::~QLinkedList()
177
178 Destroys the list. References to the values in the list, and all
179 iterators over this list, become invalid.
180*/
181
182/*! \fn template <class T> QLinkedList<T> &QLinkedList<T>::operator=(const QLinkedList<T> &other)
183
184 Assigns \a other to this list and returns a reference to this
185 list.
186*/
187
188/*! \fn template <class T> void QLinkedList<T>::swap(QLinkedList<T> &other)
189 \since 4.8
190
191 Swaps list \a other with this list. This operation is very
192 fast and never fails.
193*/
194
195/*! \fn template <class T> bool QLinkedList<T>::operator==(const QLinkedList<T> &other) const
196
197 Returns \c true if \a other is equal to this list; otherwise returns
198 false.
199
200 Two lists are considered equal if they contain the same values in
201 the same order.
202
203 This function requires the value type to implement \c
204 operator==().
205
206 \sa operator!=()
207*/
208
209/*! \fn template <class T> bool QLinkedList<T>::operator!=(const QLinkedList<T> &other) const
210
211 Returns \c true if \a other is not equal to this list; otherwise
212 returns \c false.
213
214 Two lists are considered equal if they contain the same values in
215 the same order.
216
217 This function requires the value type to implement \c
218 operator==().
219
220 \sa operator==()
221*/
222
223/*! \fn template <class T> int QLinkedList<T>::size() const
224
225 Returns the number of items in the list.
226
227 \sa isEmpty(), count()
228*/
229
230/*! \fn template <class T> void QLinkedList<T>::detach()
231
232 \internal
233*/
234
235/*! \fn template <class T> bool QLinkedList<T>::isDetached() const
236
237 \internal
238*/
239
240/*! \fn template <class T> void QLinkedList<T>::setSharable(bool sharable)
241
242 \internal
243*/
244
245/*! \fn template <class T> bool QLinkedList<T>::isSharedWith(const QLinkedList<T> &other) const
246
247 \internal
248*/
249
250/*! \fn template <class T> bool QLinkedList<T>::isEmpty() const
251
252 Returns \c true if the list contains no items; otherwise returns
253 false.
254
255 \sa size()
256*/
257
258/*! \fn template <class T> void QLinkedList<T>::clear()
259
260 Removes all the items in the list.
261
262 \sa removeAll()
263*/
264
265/*! \fn template <class T> void QLinkedList<T>::append(const T &value)
266
267 Inserts \a value at the end of the list.
268
269 Example:
270 \snippet code/src_corelib_tools_qlinkedlist.cpp 3
271
272 This is the same as list.insert(end(), \a value).
273
274 \sa operator<<(), prepend(), insert()
275*/
276
277/*! \fn template <class T> void QLinkedList<T>::prepend(const T &value)
278
279 Inserts \a value at the beginning of the list.
280
281 Example:
282 \snippet code/src_corelib_tools_qlinkedlist.cpp 4
283
284 This is the same as list.insert(begin(), \a value).
285
286 \sa append(), insert()
287*/
288
289/*! \fn template <class T> int QLinkedList<T>::removeAll(const T &value)
290
291 Removes all occurrences of \a value in the list.
292
293 Example:
294 \snippet code/src_corelib_tools_qlinkedlist.cpp 5
295
296 This function requires the value type to have an implementation of
297 \c operator==().
298
299 \sa insert()
300*/
301
302/*!
303 \fn template <class T> bool QLinkedList<T>::removeOne(const T &value)
304 \since 4.4
305
306 Removes the first occurrences of \a value in the list. Returns \c true on
307 success; otherwise returns \c false.
308
309 Example:
310 \snippet code/src_corelib_tools_qlinkedlist.cpp 6
311
312 This function requires the value type to have an implementation of
313 \c operator==().
314
315 \sa insert()
316*/
317
318/*! \fn template <class T> bool QLinkedList<T>::contains(const T &value) const
319
320 Returns \c true if the list contains an occurrence of \a value;
321 otherwise returns \c false.
322
323 This function requires the value type to have an implementation of
324 \c operator==().
325
326 \sa QLinkedListIterator::findNext(), QLinkedListIterator::findPrevious()
327*/
328
329/*! \fn template <class T> int QLinkedList<T>::count(const T &value) const
330
331 Returns the number of occurrences of \a value in the list.
332
333 This function requires the value type to have an implementation of
334 \c operator==().
335
336 \sa contains()
337*/
338
339/*! \fn template <class T> bool QLinkedList<T>::startsWith(const T &value) const
340 \since 4.5
341
342 Returns \c true if the list is not empty and its first
343 item is equal to \a value; otherwise returns \c false.
344
345 \sa isEmpty(), first()
346*/
347
348/*! \fn template <class T> bool QLinkedList<T>::endsWith(const T &value) const
349 \since 4.5
350
351 Returns \c true if the list is not empty and its last
352 item is equal to \a value; otherwise returns \c false.
353
354 \sa isEmpty(), last()
355*/
356
357/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::begin()
358
359 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the first item in
360 the list.
361
362 \sa constBegin(), end()
363*/
364
365/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::begin() const
366
367 \overload
368*/
369
370/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::cbegin() const
371 \since 5.0
372
373 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
374 in the list.
375
376 \sa begin(), cend()
377*/
378
379/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::constBegin() const
380
381 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first item
382 in the list.
383
384 \sa begin(), constEnd()
385*/
386
387/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::end()
388
389 Returns an \l{STL-style iterators}{STL-style iterator} pointing to the imaginary item
390 after the last item in the list.
391
392 \sa begin(), constEnd()
393*/
394
395/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::end() const
396
397 \overload
398*/
399
400/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::cend() const
401 \since 5.0
402
403 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
404 item after the last item in the list.
405
406 \sa cbegin(), end()
407*/
408
409/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::constEnd() const
410
411 Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary
412 item after the last item in the list.
413
414 \sa constBegin(), end()
415*/
416
417/*! \fn template <class T> QLinkedList<T>::reverse_iterator QLinkedList<T>::rbegin()
418 \since 5.6
419
420 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
421 item in the list, in reverse order.
422
423 \sa begin(), crbegin(), rend()
424*/
425
426/*! \fn template <class T> QLinkedList<T>::const_reverse_iterator QLinkedList<T>::rbegin() const
427 \since 5.6
428 \overload
429*/
430
431/*! \fn template <class T> QLinkedList<T>::const_reverse_iterator QLinkedList<T>::crbegin() const
432 \since 5.6
433
434 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
435 item in the list, in reverse order.
436
437 \sa begin(), rbegin(), rend()
438*/
439
440/*! \fn template <class T> QLinkedList<T>::reverse_iterator QLinkedList<T>::rend()
441 \since 5.6
442
443 Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
444 the last item in the list, in reverse order.
445
446 \sa end(), crend(), rbegin()
447*/
448
449/*! \fn template <class T> QLinkedList<T>::const_reverse_iterator QLinkedList<T>::rend() const
450 \since 5.6
451 \overload
452*/
453
454/*! \fn template <class T> QLinkedList<T>::const_reverse_iterator QLinkedList<T>::crend() const
455 \since 5.6
456
457 Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one
458 past the last item in the list, in reverse order.
459
460 \sa end(), rend(), rbegin()
461*/
462
463/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::insert(iterator before, const T &value)
464
465 Inserts \a value in front of the item pointed to by the iterator
466 \a before. Returns an iterator pointing at the inserted item.
467
468 \sa erase()
469*/
470
471/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::erase(iterator pos)
472
473 Removes the item pointed to by the iterator \a pos from the list,
474 and returns an iterator to the next item in the list (which may be
475 end()).
476
477 \sa insert()
478*/
479
480/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::erase(iterator begin, iterator end)
481
482 \overload
483
484 Removes all the items from \a begin up to (but not including) \a
485 end.
486*/
487
488/*! \typedef QLinkedList::Iterator
489
490 Qt-style synonym for QLinkedList::iterator.
491*/
492
493/*! \typedef QLinkedList::ConstIterator
494
495 Qt-style synonym for QLinkedList::const_iterator.
496*/
497
498/*! \typedef QLinkedList::reverse_iterator
499 \since 5.6
500
501 The QLinkedList::reverse_iterator typedef provides an STL-style non-const
502 reverse iterator for QLinkedList.
503
504 It is simply a typedef for \c{std::reverse_iterator<QLinkedList::iterator>}.
505
506 \warning Iterators on implicitly shared containers do not work
507 exactly like STL-iterators. You should avoid copying a container
508 while iterators are active on that container. For more information,
509 read \l{Implicit sharing iterator problem}.
510
511 \sa QLinkedList::rbegin(), QLinkedList::rend(), QLinkedList::const_reverse_iterator, QLinkedList::iterator
512*/
513
514/*! \typedef QLinkedList::const_reverse_iterator
515 \since 5.6
516
517 The QLinkedList::const_reverse_iterator typedef provides an STL-style const
518 reverse iterator for QLinkedList.
519
520 It is simply a typedef for \c{std::reverse_iterator<QLinkedList::const_iterator>}.
521
522 \warning Iterators on implicitly shared containers do not work
523 exactly like STL-iterators. You should avoid copying a container
524 while iterators are active on that container. For more information,
525 read \l{Implicit sharing iterator problem}.
526
527 \sa QLinkedList::rbegin(), QLinkedList::rend(), QLinkedList::reverse_iterator, QLinkedList::const_iterator
528*/
529
530/*!
531 \typedef QLinkedList::size_type
532
533 Typedef for int. Provided for STL compatibility.
534*/
535
536/*!
537 \typedef QLinkedList::value_type
538
539 Typedef for T. Provided for STL compatibility.
540*/
541
542/*!
543 \typedef QLinkedList::pointer
544
545 Typedef for T *. Provided for STL compatibility.
546*/
547
548/*!
549 \typedef QLinkedList::const_pointer
550
551 Typedef for const T *. Provided for STL compatibility.
552*/
553
554/*!
555 \typedef QLinkedList::reference
556
557 Typedef for T &. Provided for STL compatibility.
558*/
559
560/*!
561 \typedef QLinkedList::const_reference
562
563 Typedef for const T &. Provided for STL compatibility.
564*/
565
566/*!
567 \typedef QLinkedList::difference_type
568
569 Typedef for ptrdiff_t. Provided for STL compatibility.
570*/
571
572/*! \fn template <class T> int QLinkedList<T>::count() const
573
574 Same as size().
575*/
576
577/*! \fn template <class T> T& QLinkedList<T>::first()
578
579 Returns a reference to the first item in the list. This function
580 assumes that the list isn't empty.
581
582 \sa last(), isEmpty()
583*/
584
585/*! \fn template <class T> const T& QLinkedList<T>::first() const
586
587 \overload
588*/
589
590/*! \fn template <class T> T& QLinkedList<T>::last()
591
592 Returns a reference to the last item in the list. This function
593 assumes that the list isn't empty.
594
595 \sa first(), isEmpty()
596*/
597
598/*! \fn template <class T> const T& QLinkedList<T>::last() const
599
600 \overload
601*/
602
603/*! \fn template <class T> void QLinkedList<T>::removeFirst()
604
605 Removes the first item in the list.
606
607 This is the same as erase(begin()).
608
609 \sa removeLast(), erase()
610*/
611
612/*! \fn template <class T> void QLinkedList<T>::removeLast()
613
614 Removes the last item in the list.
615
616 \sa removeFirst(), erase()
617*/
618
619/*! \fn template <class T> T QLinkedList<T>::takeFirst()
620
621 Removes the first item in the list and returns it.
622
623 If you don't use the return value, removeFirst() is more
624 efficient.
625
626 \sa takeLast(), removeFirst()
627*/
628
629/*! \fn template <class T> T QLinkedList<T>::takeLast()
630
631 Removes the last item in the list and returns it.
632
633 If you don't use the return value, removeLast() is more
634 efficient.
635
636 \sa takeFirst(), removeLast()
637*/
638
639/*! \fn template <class T> void QLinkedList<T>::push_back(const T &value)
640
641 This function is provided for STL compatibility. It is equivalent
642 to append(\a value).
643*/
644
645/*! \fn template <class T> void QLinkedList<T>::push_front(const T &value)
646
647 This function is provided for STL compatibility. It is equivalent
648 to prepend(\a value).
649*/
650
651/*! \fn template <class T> T& QLinkedList<T>::front()
652
653 This function is provided for STL compatibility. It is equivalent
654 to first().
655*/
656
657/*! \fn template <class T> const T& QLinkedList<T>::front() const
658
659 \overload
660*/
661
662/*! \fn template <class T> T& QLinkedList<T>::back()
663
664 This function is provided for STL compatibility. It is equivalent
665 to last().
666*/
667
668/*! \fn template <class T> const T& QLinkedList<T>::back() const
669
670 \overload
671*/
672
673/*! \fn template <class T> void QLinkedList<T>::pop_front()
674
675 This function is provided for STL compatibility. It is equivalent
676 to removeFirst().
677*/
678
679/*! \fn template <class T> void QLinkedList<T>::pop_back()
680
681 This function is provided for STL compatibility. It is equivalent
682 to removeLast().
683*/
684
685/*! \fn template <class T> bool QLinkedList<T>::empty() const
686
687 This function is provided for STL compatibility. It is equivalent
688 to isEmpty() and returns \c true if the list is empty.
689*/
690
691/*! \fn template <class T> QLinkedList<T> &QLinkedList<T>::operator+=(const QLinkedList<T> &other)
692
693 Appends the items of the \a other list to this list and returns a
694 reference to this list.
695
696 \sa operator+(), append()
697*/
698
699/*! \fn template <class T> void QLinkedList<T>::operator+=(const T &value)
700
701 \overload
702
703 Appends \a value to the list.
704*/
705
706/*! \fn template <class T> QLinkedList<T> QLinkedList<T>::operator+(const QLinkedList<T> &other) const
707
708 Returns a list that contains all the items in this list followed
709 by all the items in the \a other list.
710
711 \sa operator+=()
712*/
713
714/*! \fn template <class T> QLinkedList<T> &QLinkedList<T>::operator<<(const QLinkedList<T> &other)
715
716 Appends the items of the \a other list to this list and returns a
717 reference to this list.
718
719 \sa operator+=(), append()
720*/
721
722/*! \fn template <class T> QLinkedList<T> &QLinkedList<T>::operator<<(const T &value)
723
724 \overload
725
726 Appends \a value to the list.
727*/
728
729/*! \class QLinkedList::iterator
730 \inmodule QtCore
731 \obsolete
732 \brief The QLinkedList::iterator class provides an STL-style non-const iterator for QLinkedList.
733
734 QLinkedList features both \l{STL-style iterators} and
735 \l{Java-style iterators}. The STL-style iterators are more
736 low-level and more cumbersome to use; on the other hand, they are
737 slightly faster and, for developers who already know STL, have
738 the advantage of familiarity.
739
740 QLinkedList\<T\>::iterator allows you to iterate over a
741 QLinkedList\<T\> and to modify the list item associated with the
742 iterator. If you want to iterate over a const QLinkedList, use
743 QLinkedList::const_iterator instead. It is generally good
744 practice to use QLinkedList::const_iterator on a non-const
745 QLinkedList as well, unless you need to change the QLinkedList
746 through the iterator. Const iterators are slightly faster, and
747 can improve code readability.
748
749 The default QLinkedList::iterator constructor creates an
750 uninitialized iterator. You must initialize it using a
751 function like QLinkedList::begin(), QLinkedList::end(), or
752 QLinkedList::insert() before you can start iterating. Here's a
753 typical loop that prints all the items stored in a list:
754
755 \snippet code/src_corelib_tools_qlinkedlist.cpp 7
756
757 STL-style iterators can be used as arguments to \l{generic
758 algorithms}. For example, here's how to find an item in the list:
759
760 \snippet code/src_corelib_tools_qlinkedlist.cpp 8
761
762 Let's see a few examples of things we can do with a
763 QLinkedList::iterator that we cannot do with a QLinkedList::const_iterator.
764 Here's an example that increments every value stored in a
765 QLinkedList\<int\> by 2:
766
767 \snippet code/src_corelib_tools_qlinkedlist.cpp 9
768
769 Here's an example that removes all the items that start with an
770 underscore character in a QLinkedList\<QString\>:
771
772 \snippet code/src_corelib_tools_qlinkedlist.cpp 10
773
774 The call to QLinkedList::erase() removes the item pointed to by
775 the iterator from the list, and returns an iterator to the next
776 item. Here's another way of removing an item while iterating:
777
778 \snippet code/src_corelib_tools_qlinkedlist.cpp 11
779
780 It might be tempting to write code like this:
781
782 \snippet code/src_corelib_tools_qlinkedlist.cpp 12
783
784 However, this will potentially crash in \c{++i}, because \c i is
785 a dangling iterator after the call to erase().
786
787 Multiple iterators can be used on the same list. If you add items
788 to the list, existing iterators will remain valid. If you remove
789 items from the list, iterators that point to the removed items
790 will become dangling iterators.
791
792 \warning Iterators on implicitly shared containers do not work
793 exactly like STL-iterators. You should avoid copying a container
794 while iterators are active on that container. For more information,
795 read \l{Implicit sharing iterator problem}.
796
797 \sa QLinkedList::const_iterator, QMutableLinkedListIterator
798*/
799
800/*! \fn template <class T> QLinkedList<T>::iterator::iterator()
801
802 Constructs an uninitialized iterator.
803
804 Functions like operator*() and operator++() should not be called
805 on an uninitialized iterator. Use operator=() to assign a value
806 to it before using it.
807
808 \sa QLinkedList::begin(), QLinkedList::end()
809*/
810
811/*! \fn template <class T> QLinkedList<T>::iterator::iterator(Node *node)
812
813 \internal
814*/
815
816/*! \typedef QLinkedList::iterator::iterator_category
817
818 \internal
819*/
820
821/*! \typedef QLinkedList::iterator::difference_type
822
823 \internal
824*/
825
826/*! \typedef QLinkedList::iterator::value_type
827
828 \internal
829*/
830
831/*! \typedef QLinkedList::iterator::pointer
832
833 \internal
834*/
835
836/*! \typedef QLinkedList::iterator::reference
837
838 \internal
839*/
840
841/*! \fn template <class T> QLinkedList<T>::iterator::iterator(const iterator &other)
842
843 Constructs a copy of \a other.
844*/
845
846/*! \fn template <class T> QLinkedList<T>::iterator &QLinkedList<T>::iterator::operator=(const iterator &other)
847
848 Assigns \a other to this iterator.
849*/
850
851/*!
852 \fn template <class T> QLinkedList<T> &QLinkedList<T>::operator=(QLinkedList<T> &&other)
853
854 Move-assigns \a other to this QLinkedList instance.
855
856 \since 5.2
857*/
858
859/*! \fn template <class T> T &QLinkedList<T>::iterator::operator*() const
860
861 Returns a modifiable reference to the current item.
862
863 You can change the value of an item by using operator*() on the
864 left side of an assignment, for example:
865
866 \snippet code/src_corelib_tools_qlinkedlist.cpp 13
867
868 \sa operator->()
869*/
870
871/*! \fn template <class T> T *QLinkedList<T>::iterator::operator->() const
872
873 Returns a pointer to the current item.
874
875 \sa operator*()
876*/
877
878/*!
879 \fn template <class T> bool QLinkedList<T>::iterator::operator==(const iterator &other) const
880 \fn template <class T> bool QLinkedList<T>::iterator::operator==(const const_iterator &other) const
881
882 Returns \c true if \a other points to the same item as this
883 iterator; otherwise returns \c false.
884
885 \sa operator!=()
886*/
887
888/*!
889 \fn template <class T> bool QLinkedList<T>::iterator::operator!=(const iterator &other) const
890 \fn template <class T> bool QLinkedList<T>::iterator::operator!=(const const_iterator &other) const
891
892 Returns \c true if \a other points to a different item than this
893 iterator; otherwise returns \c false.
894
895 \sa operator==()
896*/
897
898/*! \fn template <class T> QLinkedList<T>::iterator &QLinkedList<T>::iterator::operator++()
899
900 The prefix ++ operator (\c{++it}) advances the iterator to the
901 next item in the list and returns an iterator to the new current
902 item.
903
904 Calling this function on QLinkedList::end() leads to undefined
905 results.
906
907 \sa operator--()
908*/
909
910/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::iterator::operator++(int)
911
912 \overload
913
914 The postfix ++ operator (\c{it++}) advances the iterator to the
915 next item in the list and returns an iterator to the previously
916 current item.
917*/
918
919/*! \fn template <class T> QLinkedList<T>::iterator &QLinkedList<T>::iterator::operator--()
920
921 The prefix -- operator (\c{--it}) makes the preceding item
922 current and returns an iterator to the new current item.
923
924 Calling this function on QLinkedList::begin() leads to undefined
925 results.
926
927 \sa operator++()
928*/
929
930/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::iterator::operator--(int)
931
932 \overload
933
934 The postfix -- operator (\c{it--}) makes the preceding item
935 current and returns an iterator to the previously current item.
936*/
937
938/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::iterator::operator+(int j) const
939
940 Returns an iterator to the item at \a j positions forward from
941 this iterator. (If \a j is negative, the iterator goes backward.)
942
943 This operation can be slow for large \a j values.
944
945 \sa operator-()
946
947*/
948
949/*! \fn template <class T> QLinkedList<T>::iterator QLinkedList<T>::iterator::operator-(int j) const
950
951 Returns an iterator to the item at \a j positions backward from
952 this iterator. (If \a j is negative, the iterator goes forward.)
953
954 This operation can be slow for large \a j values.
955
956 \sa operator+()
957*/
958
959/*! \fn template <class T> QLinkedList<T>::iterator &QLinkedList<T>::iterator::operator+=(int j)
960
961 Advances the iterator by \a j items. (If \a j is negative, the
962 iterator goes backward.)
963
964 \sa operator-=(), operator+()
965*/
966
967/*! \fn template <class T> QLinkedList<T>::iterator &QLinkedList<T>::iterator::operator-=(int j)
968
969 Makes the iterator go back by \a j items. (If \a j is negative,
970 the iterator goes forward.)
971
972 \sa operator+=(), operator-()
973*/
974
975/*! \class QLinkedList::const_iterator
976 \inmodule QtCore
977 \obsolete
978 \brief The QLinkedList::const_iterator class provides an STL-style const iterator for QLinkedList.
979
980 QLinkedList features both \l{STL-style iterators} and
981 \l{Java-style iterators}. The STL-style iterators are more
982 low-level and more cumbersome to use; on the other hand, they are
983 slightly faster and, for developers who already know STL, have
984 the advantage of familiarity.
985
986 QLinkedList\<T\>::const_iterator allows you to iterate over a
987 QLinkedList\<T\>. If you want modify the QLinkedList as you iterate
988 over it, you must use QLinkedList::iterator instead. It is
989 generally good practice to use QLinkedList::const_iterator on a
990 non-const QLinkedList as well, unless you need to change the
991 QLinkedList through the iterator. Const iterators are slightly
992 faster, and can improve code readability.
993
994 The default QLinkedList::const_iterator constructor creates an
995 uninitialized iterator. You must initialize it using a function
996 like QLinkedList::constBegin(), QLinkedList::constEnd(), or
997 QLinkedList::insert() before you can start iterating. Here's a
998 typical loop that prints all the items stored in a list:
999
1000 \snippet code/src_corelib_tools_qlinkedlist.cpp 14
1001
1002 STL-style iterators can be used as arguments to \l{generic
1003 algorithms}. For example, here's how to find an item in the list:
1004
1005 \snippet code/src_corelib_tools_qlinkedlist.cpp 15
1006
1007 Multiple iterators can be used on the same list. If you add items
1008 to the list, existing iterators will remain valid. If you remove
1009 items from the list, iterators that point to the removed items
1010 will become dangling iterators.
1011
1012 \warning Iterators on implicitly shared containers do not work
1013 exactly like STL-iterators. You should avoid copying a container
1014 while iterators are active on that container. For more information,
1015 read \l{Implicit sharing iterator problem}.
1016
1017 \sa QLinkedList::iterator, QLinkedListIterator
1018*/
1019
1020/*! \fn template <class T> QLinkedList<T>::const_iterator::const_iterator()
1021
1022 Constructs an uninitialized iterator.
1023
1024 Functions like operator*() and operator++() should not be called
1025 on an uninitialized iterator. Use operator=() to assign a value
1026 to it before using it.
1027
1028 \sa QLinkedList::constBegin(), QLinkedList::constEnd()
1029*/
1030
1031/*! \fn template <class T> QLinkedList<T>::const_iterator::const_iterator(Node *node)
1032
1033 \internal
1034*/
1035
1036/*! \typedef QLinkedList::const_iterator::iterator_category
1037
1038 \internal
1039*/
1040
1041/*! \typedef QLinkedList::const_iterator::difference_type
1042
1043 \internal
1044*/
1045
1046/*! \typedef QLinkedList::const_iterator::value_type
1047
1048 \internal
1049*/
1050
1051/*! \typedef QLinkedList::const_iterator::pointer
1052
1053 \internal
1054*/
1055
1056/*! \typedef QLinkedList::const_iterator::reference
1057
1058 \internal
1059*/
1060
1061/*! \fn template <class T> QLinkedList<T>::const_iterator::const_iterator(const const_iterator &other)
1062
1063 Constructs a copy of \a other.
1064*/
1065
1066/*! \fn template <class T> QLinkedList<T>::const_iterator::const_iterator(iterator other)
1067
1068 Constructs a copy of \a other.
1069*/
1070
1071/*! \fn template <class T> typename QLinkedList<T>::const_iterator &QLinkedList<T>::const_iterator::operator=(const const_iterator &other)
1072
1073 Assigns \a other to this iterator.
1074*/
1075
1076/*! \fn template <class T> const T &QLinkedList<T>::const_iterator::operator*() const
1077
1078 Returns a reference to the current item.
1079
1080 \sa operator->()
1081*/
1082
1083/*! \fn template <class T> const T *QLinkedList<T>::const_iterator::operator->() const
1084
1085 Returns a pointer to the current item.
1086
1087 \sa operator*()
1088*/
1089
1090/*! \fn template <class T> bool QLinkedList<T>::const_iterator::operator==(const const_iterator &other) const
1091
1092 Returns \c true if \a other points to the same item as this
1093 iterator; otherwise returns \c false.
1094
1095 \sa operator!=()
1096*/
1097
1098/*! \fn template <class T> bool QLinkedList<T>::const_iterator::operator!=(const const_iterator &other) const
1099
1100 Returns \c true if \a other points to a different item than this
1101 iterator; otherwise returns \c false.
1102
1103 \sa operator==()
1104*/
1105
1106/*! \fn template <class T> QLinkedList<T>::const_iterator &QLinkedList<T>::const_iterator::operator++()
1107
1108 The prefix ++ operator (\c{++it}) advances the iterator to the
1109 next item in the list and returns an iterator to the new current
1110 item.
1111
1112 Calling this function on QLinkedList<T>::constEnd() leads to
1113 undefined results.
1114
1115 \sa operator--()
1116*/
1117
1118/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::const_iterator::operator++(int)
1119
1120 \overload
1121
1122 The postfix ++ operator (\c{it++}) advances the iterator to the
1123 next item in the list and returns an iterator to the previously
1124 current item.
1125*/
1126
1127/*! \fn template <class T> QLinkedList<T>::const_iterator &QLinkedList<T>::const_iterator::operator--()
1128
1129 The prefix -- operator (\c{--it}) makes the preceding item
1130 current and returns an iterator to the new current item.
1131
1132 Calling this function on QLinkedList::begin() leads to undefined
1133 results.
1134
1135 \sa operator++()
1136*/
1137
1138/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::const_iterator::operator--(int)
1139
1140 \overload
1141
1142 The postfix -- operator (\c{it--}) makes the preceding item
1143 current and returns an iterator to the previously current item.
1144*/
1145
1146/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::const_iterator::operator+(int j) const
1147
1148 Returns an iterator to the item at \a j positions forward from
1149 this iterator. (If \a j is negative, the iterator goes backward.)
1150
1151 This operation can be slow for large \a j values.
1152
1153 \sa operator-()
1154*/
1155
1156/*! \fn template <class T> QLinkedList<T>::const_iterator QLinkedList<T>::const_iterator::operator-(int j) const
1157
1158 This function returns an iterator to the item at \a j positions backward from
1159 this iterator. (If \a j is negative, the iterator goes forward.)
1160
1161 This operation can be slow for large \a j values.
1162
1163 \sa operator+()
1164*/
1165
1166/*! \fn template <class T> QLinkedList<T>::const_iterator &QLinkedList<T>::const_iterator::operator+=(int j)
1167
1168 Advances the iterator by \a j items. (If \a j is negative, the
1169 iterator goes backward.)
1170
1171 This operation can be slow for large \a j values.
1172
1173 \sa operator-=(), operator+()
1174*/
1175
1176/*! \fn template <class T> QLinkedList<T>::const_iterator &QLinkedList<T>::const_iterator::operator-=(int j)
1177
1178 Makes the iterator go back by \a j items. (If \a j is negative,
1179 the iterator goes forward.)
1180
1181 This operation can be slow for large \a j values.
1182
1183 \sa operator+=(), operator-()
1184*/
1185
1186/*! \fn template <class T> QDataStream &operator<<(QDataStream &out, const QLinkedList<T> &list)
1187 \relates QLinkedList
1188
1189 Writes the linked list \a list to stream \a out.
1190
1191 This function requires the value type to implement \c
1192 operator<<().
1193
1194 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1195*/
1196
1197/*! \fn template <class T> QDataStream &operator>>(QDataStream &in, QLinkedList<T> &list)
1198 \relates QLinkedList
1199
1200 Reads a linked list from stream \a in into \a list.
1201
1202 This function requires the value type to implement \c operator>>().
1203
1204 \sa{Serializing Qt Data Types}{Format of the QDataStream operators}
1205*/
1206
1207/*!
1208 \since 4.1
1209 \fn template <class T> QLinkedList<T> QLinkedList<T>::fromStdList(const std::list<T> &list)
1210
1211 Returns a QLinkedList object with the data contained in \a list.
1212 The order of the elements in the QLinkedList is the same as in \a
1213 list.
1214
1215 Example:
1216
1217 \snippet code/src_corelib_tools_qlinkedlist.cpp 16
1218
1219 \sa toStdList()
1220*/
1221
1222/*!
1223 \since 4.1
1224 \fn template <class T> std::list<T> QLinkedList<T>::toStdList() const
1225
1226 Returns a std::list object with the data contained in this
1227 QLinkedList. Example:
1228
1229 \snippet code/src_corelib_tools_qlinkedlist.cpp 17
1230
1231 \sa fromStdList()
1232*/
1233
1234QT_WARNING_POP
1235
1236#endif // QT_DEPRECATED_SINCE(5, 15)
1237
1238QT_END_NAMESPACE
1239

source code of qtbase/src/corelib/tools/qlinkedlist.cpp