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 QtQml 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#include "qintrusivelist_p.h"
41
42/*!
43\class QIntrusiveList
44\brief The QIntrusiveList class is a template class that provides a list of objects using static storage.
45\internal
46
47QIntrusiveList creates a linked list of objects. Adding and removing objects from the
48QIntrusiveList is a constant time operation and is very quick. The list performs no memory
49allocations, but does require the objects being added to the list to contain a QIntrusiveListNode
50instance for the list's use. Even so, for small lists QIntrusiveList uses less memory than Qt's
51other list classes.
52
53As QIntrusiveList uses storage inside the objects in the list, each object can only be in one
54list at a time. Objects are inserted by the insert() method. If the object is already
55in a list (including the one it is being inserted into) it is first removed, and then inserted
56at the head of the list. QIntrusiveList is a last-in-first-out list. That is, following an
57insert() the inserted object becomes the list's first() object.
58
59\code
60struct MyObject {
61 MyObject(int value) : value(value) {}
62
63 int value;
64 QIntrusiveListNode node;
65};
66typedef QIntrusiveList<MyObject, &MyObject::node> MyObjectList;
67
68void foo() {
69 MyObjectList list;
70
71 MyObject m0(0);
72 MyObject m1(1);
73 MyObject m2(2);
74
75 list.insert(&m0);
76 list.insert(&m1);
77 list.insert(&m2);
78
79 // QIntrusiveList is LIFO, so will print: 2... 1... 0...
80 for (MyObjectList::iterator iter = list.begin(); iter != list.end(); ++iter) {
81 qWarning() << iter->value;
82 }
83}
84\endcode
85*/
86
87
88/*!
89\fn QIntrusiveList::QIntrusiveList();
90
91Construct an empty list.
92*/
93
94/*!
95\fn QIntrusiveList::~QIntrusiveList();
96
97Destroy the list. All entries are removed.
98*/
99
100/*!
101\fn void QIntrusiveList::insert(N *object);
102
103Insert \a object into the list. If \a object is a member of this, or another list, it will be
104removed and inserted at the head of this list.
105*/
106
107/*!
108\fn void QIntrusiveList::remove(N *object);
109
110Remove \a object from the list. \a object must not be null.
111*/
112
113/*!
114\fn bool QIntrusiveList::contains(N *object) const
115
116Returns true if the list contains \a object; otherwise returns false.
117*/
118
119/*!
120\fn N *QIntrusiveList::first() const
121
122Returns the first entry in this list, or null if the list is empty.
123*/
124
125/*!
126\fn N *QIntrusiveList::next(N *current)
127
128Returns the next object after \a current, or null if \a current is the last object. \a current cannot be null.
129*/
130
131/*!
132\fn iterator QIntrusiveList::begin()
133
134Returns an STL-style interator pointing to the first item in the list.
135
136\sa end()
137*/
138
139/*!
140\fn iterator QIntrusiveList::end()
141
142Returns an STL-style iterator pointing to the imaginary item after the last item in the list.
143
144\sa begin()
145*/
146
147/*!
148\fn iterator &QIntrusiveList::iterator::erase()
149
150Remove the current object from the list, and return an iterator to the next element.
151*/
152
153/*!
154 \class QIntrusiveListNode
155 \internal
156*/
157
158/*!
159\fn QIntrusiveListNode::QIntrusiveListNode()
160
161Create a QIntrusiveListNode.
162*/
163
164/*!
165\fn QIntrusiveListNode::~QIntrusiveListNode()
166
167Destroy the QIntrusiveListNode. If the node is in a list, it is removed.
168*/
169
170/*!
171\fn void QIntrusiveListNode::remove()
172
173If in a list, remove this node otherwise do nothing.
174*/
175
176/*!
177\fn bool QIntrusiveListNode::isInList() const
178
179Returns true if this node is in a list, false otherwise.
180*/
181
182

source code of qtdeclarative/src/qml/qml/ftw/qintrusivelist.cpp