1 | // Copyright (C) 2016 The Qt Company Ltd. |
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
3 | |
4 | #include "qintrusivelist_p.h" |
5 | |
6 | /*! |
7 | \class QIntrusiveList |
8 | \brief The QIntrusiveList class is a template class that provides a list of objects using static storage. |
9 | \internal |
10 | |
11 | QIntrusiveList creates a linked list of objects. Adding and removing objects from the |
12 | QIntrusiveList is a constant time operation and is very quick. The list performs no memory |
13 | allocations, but does require the objects being added to the list to contain a QIntrusiveListNode |
14 | instance for the list's use. Even so, for small lists QIntrusiveList uses less memory than Qt's |
15 | other list classes. |
16 | |
17 | As QIntrusiveList uses storage inside the objects in the list, each object can only be in one |
18 | list at a time. Objects are inserted by the insert() method. If the object is already |
19 | in a list (including the one it is being inserted into) it is first removed, and then inserted |
20 | at the head of the list. QIntrusiveList is a last-in-first-out list. That is, following an |
21 | insert() the inserted object becomes the list's first() object. |
22 | |
23 | \code |
24 | struct MyObject { |
25 | MyObject(int value) : value(value) {} |
26 | |
27 | int value; |
28 | QIntrusiveListNode node; |
29 | }; |
30 | typedef QIntrusiveList<MyObject, &MyObject::node> MyObjectList; |
31 | |
32 | void foo() { |
33 | MyObjectList list; |
34 | |
35 | MyObject m0(0); |
36 | MyObject m1(1); |
37 | MyObject m2(2); |
38 | |
39 | list.insert(&m0); |
40 | list.insert(&m1); |
41 | list.insert(&m2); |
42 | |
43 | // QIntrusiveList is LIFO, so will print: 2... 1... 0... |
44 | for (MyObjectList::iterator iter = list.begin(); iter != list.end(); ++iter) { |
45 | qWarning() << iter->value; |
46 | } |
47 | } |
48 | \endcode |
49 | */ |
50 | |
51 | |
52 | /*! |
53 | \fn QIntrusiveList::QIntrusiveList(); |
54 | |
55 | Construct an empty list. |
56 | */ |
57 | |
58 | /*! |
59 | \fn QIntrusiveList::~QIntrusiveList(); |
60 | |
61 | Destroy the list. All entries are removed. |
62 | */ |
63 | |
64 | /*! |
65 | \fn void QIntrusiveList::insert(N *object); |
66 | |
67 | Insert \a object into the list. If \a object is a member of this, or another list, it will be |
68 | removed and inserted at the head of this list. |
69 | */ |
70 | |
71 | /*! |
72 | \fn void QIntrusiveList::remove(N *object); |
73 | |
74 | Remove \a object from the list. \a object must not be null. |
75 | */ |
76 | |
77 | /*! |
78 | \fn bool QIntrusiveList::contains(N *object) const |
79 | |
80 | Returns true if the list contains \a object; otherwise returns false. |
81 | */ |
82 | |
83 | /*! |
84 | \fn N *QIntrusiveList::first() const |
85 | |
86 | Returns the first entry in this list, or null if the list is empty. |
87 | */ |
88 | |
89 | /*! |
90 | \fn N *QIntrusiveList::next(N *current) |
91 | |
92 | Returns the next object after \a current, or null if \a current is the last object. \a current cannot be null. |
93 | */ |
94 | |
95 | /*! |
96 | \fn iterator QIntrusiveList::begin() |
97 | |
98 | Returns an STL-style interator pointing to the first item in the list. |
99 | |
100 | \sa end() |
101 | */ |
102 | |
103 | /*! |
104 | \fn iterator QIntrusiveList::end() |
105 | |
106 | Returns an STL-style iterator pointing to the imaginary item after the last item in the list. |
107 | |
108 | \sa begin() |
109 | */ |
110 | |
111 | /*! |
112 | \fn iterator &QIntrusiveList::iterator::erase() |
113 | |
114 | Remove the current object from the list, and return an iterator to the next element. |
115 | */ |
116 | |
117 | /*! |
118 | \class QIntrusiveListNode |
119 | \internal |
120 | */ |
121 | |
122 | /*! |
123 | \fn QIntrusiveListNode::QIntrusiveListNode() |
124 | |
125 | Create a QIntrusiveListNode. |
126 | */ |
127 | |
128 | /*! |
129 | \fn QIntrusiveListNode::~QIntrusiveListNode() |
130 | |
131 | Destroy the QIntrusiveListNode. If the node is in a list, it is removed. |
132 | */ |
133 | |
134 | /*! |
135 | \fn void QIntrusiveListNode::remove() |
136 | |
137 | If in a list, remove this node otherwise do nothing. |
138 | */ |
139 | |
140 | /*! |
141 | \fn bool QIntrusiveListNode::isInList() const |
142 | |
143 | Returns true if this node is in a list, false otherwise. |
144 | */ |
145 | |
146 | |