vcs.maemo.org Git - someplayer/blob - src/taglib/toolkit/tlist.h

   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  19  *   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 memebers 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     uint size() const;
 151     bool isEmpty() const;
 152
 153     /*!
 154      * Find the first occurrence of \a value.
 155      */
 156     Iterator find(const T &value);
 157
 158     /*!
 159      * Find the first occurrence of \a value.
 160      */
 161     ConstIterator find(const T &value) const;
 162
 163     /*!
 164      * Returns true if the list contains \a value.
 165      */
 166     bool contains(const T &value) const;
 167
 168     /*!
 169      * Erase the item at \a it from the list.
 170      */
 171     Iterator erase(Iterator it);
 172
 173     /*!
 174      * Returns a reference to the first item in the list.
 175      */
 176     const T &front() const;
 177
 178     /*!
 179      * Returns a reference to the first item in the list.
 180      */
 181     T &front();
 182
 183     /*!
 184      * Returns a reference to the last item in the list.
 185      */
 186     const T &back() const;
 187
 188     /*!
 189      * Returns a reference to the last item in the list.
 190      */
 191     T &back();
 192
 193     /*!
 194      * Auto delete the members of the list when the last reference to the list
 195      * passes out of scope.  This will have no effect on lists which do not
 196      * contain a pointer type.
 197      *
 198      * \note This relies on partial template instantiation -- most modern C++
 199      * compilers should now support this.
 200      */
 201     void setAutoDelete(bool autoDelete);
 202
 203     /*!
 204      * Returns a reference to item \a i in the list.
 205      *
 206      * \warning This method is slow.  Use iterators to loop through the list.
 207      */
 208     T &operator[](uint i);
 209
 210     /*!
 211      * Returns a const reference to item \a i in the list.
 212      *
 213      * \warning This method is slow.  Use iterators to loop through the list.
 214      */
 215     const T &operator[](uint i) const;
 216
 217     /*!
 218      * Make a shallow, implicitly shared, copy of \a l.  Because this is
 219      * implicitly shared, this method is lightweight and suitable for
 220      * pass-by-value usage.
 221      */
 222     List<T> &operator=(const List<T> &l);
 223
 224     /*!
 225      * Compares this list with \a l and returns true if all of the elements are
 226      * the same.
 227      */
 228     bool operator==(const List<T> &l) const;
 229
 230   protected:
 231     /*
 232      * If this List is being shared via implicit sharing, do a deep copy of the
 233      * data and separate from the shared members.  This should be called by all
 234      * non-const subclass members.
 235      */
 236     void detach();
 237
 238   private:
 239 #ifndef DO_NOT_DOCUMENT
 240     template <class TP> class ListPrivate;
 241     ListPrivate<T> *d;
 242 #endif
 243   };
 244
 245 }
 246
 247 // Since GCC doesn't support the "export" keyword, we have to include the
 248 // implementation.
 249
 250 #include "tlist.tcc"
 251
 252 #endif