1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 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 33 namespace 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 * Exchanges the content of this list by the content of \a l. 234 */ 235 void swap(List<T> &l); 236 237 /*! 238 * Compares this list with \a l and returns true if all of the elements are 239 * the same. 240 */ 241 bool operator==(const List<T> &l) const; 242 243 /*! 244 * Compares this list with \a l and returns true if the lists differ. 245 */ 246 bool operator!=(const List<T> &l) const; 247 248 protected: 249 /* 250 * If this List is being shared via implicit sharing, do a deep copy of the 251 * data and separate from the shared members. This should be called by all 252 * non-const subclass members. 253 */ 254 void detach(); 255 256 private: 257 #ifndef DO_NOT_DOCUMENT 258 template <class TP> class ListPrivate; 259 ListPrivate<T> *d; 260 #endif 261 }; 262 263 } 264 265 // Since GCC doesn't support the "export" keyword, we have to include the 266 // implementation. 267 268 #include "tlist.tcc" 269 270 #endif 271