1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
5
6/***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
10 * *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA *
19 * 02110-1301 USA *
20 * *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
25
26#ifndef TAGLIB_LIST_H
27#define TAGLIB_LIST_H
28
29#include "taglib.h"
30
31#include <list>
32
33namespace TagLib {
34
35 //! A generic, implicitly shared list.
36
37 /*!
38 * This is basic generic list that's somewhere between a std::list and a
39 * QValueList. This class is implicitly shared. For example:
40 *
41 * \code
42 *
43 * TagLib::List<int> l = someOtherIntList;
44 *
45 * \endcode
46 *
47 * The above example is very cheap. This also makes lists suitable for the
48 * return types of functions. The above example will just copy a pointer rather
49 * than copying the data in the list. When your \e shared list's data changes,
50 * only \e then will the data be copied.
51 */
52
53 template <class T> class List
54 {
55 public:
56#ifndef DO_NOT_DOCUMENT
57 typedef typename std::list<T>::iterator Iterator;
58 typedef typename std::list<T>::const_iterator ConstIterator;
59#endif
60
61 /*!
62 * Constructs an empty list.
63 */
64 List();
65
66 /*!
67 * Make a shallow, implicitly shared, copy of \a l. Because this is
68 * implicitly shared, this method is lightweight and suitable for
69 * pass-by-value usage.
70 */
71 List(const List<T> &l);
72
73 /*!
74 * Destroys this List instance. If auto deletion is enabled and this list
75 * contains a pointer type all of the members are also deleted.
76 */
77 virtual ~List();
78
79 /*!
80 * Returns an STL style iterator to the beginning of the list. See
81 * std::list::const_iterator for the semantics.
82 */
83 Iterator begin();
84
85 /*!
86 * Returns an STL style constant iterator to the beginning of the list. See
87 * std::list::iterator for the semantics.
88 */
89 ConstIterator begin() const;
90
91 /*!
92 * Returns an STL style iterator to the end of the list. See
93 * std::list::iterator for the semantics.
94 */
95 Iterator end();
96
97 /*!
98 * Returns an STL style constant iterator to the end of the list. See
99 * std::list::const_iterator for the semantics.
100 */
101 ConstIterator end() const;
102
103 /*!
104 * Inserts a copy of \a value before \a it.
105 */
106 Iterator insert(Iterator it, const T &value);
107
108 /*!
109 * Inserts the \a value into the list. This assumes that the list is
110 * currently sorted. If \a unique is true then the value will not
111 * be inserted if it is already in the list.
112 */
113 List<T> &sortedInsert(const T &value, bool unique = false);
114
115 /*!
116 * Appends \a item to the end of the list and returns a reference to the
117 * list.
118 */
119 List<T> &append(const T &item);
120
121 /*!
122 * Appends all of the values in \a l to the end of the list and returns a
123 * reference to the list.
124 */
125 List<T> &append(const List<T> &l);
126
127 /*!
128 * Prepends \a item to the beginning list and returns a reference to the
129 * list.
130 */
131 List<T> &prepend(const T &item);
132
133 /*!
134 * Prepends all of the items in \a l to the beginning list and returns a
135 * reference to the list.
136 */
137 List<T> &prepend(const List<T> &l);
138
139 /*!
140 * Clears the list. If auto deletion is enabled and this list contains a
141 * pointer type the members are also deleted.
142 *
143 * \see setAutoDelete()
144 */
145 List<T> &clear();
146
147 /*!
148 * Returns the number of elements in the list.
149 *
150 * \see isEmpty()
151 */
152 unsigned int size() const;
153
154 /*!
155 * Returns whether or not the list is empty.
156 *
157 * \see size()
158 */
159 bool isEmpty() const;
160
161 /*!
162 * Find the first occurrence of \a value.
163 */
164 Iterator find(const T &value);
165
166 /*!
167 * Find the first occurrence of \a value.
168 */
169 ConstIterator find(const T &value) const;
170
171 /*!
172 * Returns true if the list contains \a value.
173 */
174 bool contains(const T &value) const;
175
176 /*!
177 * Erase the item at \a it from the list.
178 */
179 Iterator erase(Iterator it);
180
181 /*!
182 * Returns a reference to the first item in the list.
183 */
184 const T &front() const;
185
186 /*!
187 * Returns a reference to the first item in the list.
188 */
189 T &front();
190
191 /*!
192 * Returns a reference to the last item in the list.
193 */
194 const T &back() const;
195
196 /*!
197 * Returns a reference to the last item in the list.
198 */
199 T &back();
200
201 /*!
202 * Auto delete the members of the list when the last reference to the list
203 * passes out of scope. This will have no effect on lists which do not
204 * contain a pointer type.
205 *
206 * \note This relies on partial template instantiation -- most modern C++
207 * compilers should now support this.
208 */
209 void setAutoDelete(bool autoDelete);
210
211 /*!
212 * Returns a reference to item \a i in the list.
213 *
214 * \warning This method is slow. Use iterators to loop through the list.
215 */
216 T &operator[](unsigned int i);
217
218 /*!
219 * Returns a const reference to item \a i in the list.
220 *
221 * \warning This method is slow. Use iterators to loop through the list.
222 */
223 const T &operator[](unsigned int i) const;
224
225 /*!
226 * Make a shallow, implicitly shared, copy of \a l. Because this is
227 * implicitly shared, this method is lightweight and suitable for
228 * pass-by-value usage.
229 */
230 List<T> &operator=(const List<T> &l);
231
232 /*!
233 * Compares this list with \a l and returns true if all of the elements are
234 * the same.
235 */
236 bool operator==(const List<T> &l) const;
237
238 /*!
239 * Compares this list with \a l and returns true if the lists differ.
240 */
241 bool operator!=(const List<T> &l) const;
242
243 protected:
244 /*
245 * If this List is being shared via implicit sharing, do a deep copy of the
246 * data and separate from the shared members. This should be called by all
247 * non-const subclass members.
248 */
249 void detach();
250
251 private:
252#ifndef DO_NOT_DOCUMENT
253 template <class TP> class ListPrivate;
254 ListPrivate<T> *d;
255#endif
256 };
257
258}
259
260// Since GCC doesn't support the "export" keyword, we have to include the
261// implementation.
262
263#include "tlist.tcc"
264
265#endif
266