git.maemo.org Git - someplayer/blob - src/taglib/toolkit/tmap.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_MAP_H
  27 #define TAGLIB_MAP_H
  28
  29 #include <map>
  30 using namespace std;
  31
  32 #include "taglib.h"
  33
  34 namespace TagLib {
  35
  36   //! A generic, implicitly shared map.
  37
  38   /*!
  39    * This implements a standard map container that associates a key with a value
  40    * and has fast key-based lookups.  This map is also implicitly shared making
  41    * it suitable for pass-by-value usage.
  42    */
  43
  44   template <class Key, class T> class Map
  45   {
  46   public:
  47 #ifndef DO_NOT_DOCUMENT
  48 #ifdef WANT_CLASS_INSTANTIATION_OF_MAP
  49     // Some STL implementations get snippy over the use of the
  50     // class keyword to distinguish different templates; Sun Studio
  51     // in particular finds multiple specializations in certain rare
  52     // cases and complains about that. GCC doesn't seem to mind,
  53     // and uses the typedefs further below without the class keyword.
  54     // Not all the specializations of Map can use the class keyword
  55     // (when T is not actually a class type), so don't apply this
  56     // generally.
  57     typedef typename std::map<class Key, class T>::iterator Iterator;
  58     typedef typename std::map<class Key, class T>::const_iterator ConstIterator;
  59 #else
  60     typedef typename std::map<Key, T>::iterator Iterator;
  61     typedef typename std::map<Key, T>::const_iterator ConstIterator;
  62 #endif
  63 #endif
  64
  65     /*!
  66      * Constructs an empty Map.
  67      */
  68     Map();
  69
  70     /*!
  71      * Make a shallow, implicitly shared, copy of \a m.  Because this is
  72      * implicitly shared, this method is lightweight and suitable for
  73      * pass-by-value usage.
  74      */
  75     Map(const Map<Key, T> &m);
  76
  77     /*!
  78      * Destroys this instance of the Map.
  79      */
  80     virtual ~Map();
  81
  82     /*!
  83      * Returns an STL style iterator to the beginning of the map.  See
  84      * std::map::iterator for the semantics.
  85      */
  86     Iterator begin();
  87
  88     /*!
  89      * Returns an STL style iterator to the beginning of the map.  See
  90      * std::map::const_iterator for the semantics.
  91      */
  92     ConstIterator begin() const;
  93
  94     /*!
  95      * Returns an STL style iterator to the end of the map.  See
  96      * std::map::iterator for the semantics.
  97      */
  98     Iterator end();
  99
 100     /*!
 101      * Returns an STL style iterator to the end of the map.  See
 102      * std::map::const_iterator for the semantics.
 103      */
 104     ConstIterator end() const;
 105
 106     /*!
 107      * Inserts \a value under \a key in the map.  If a value for \a key already
 108      * exists it will be overwritten.
 109      */
 110     Map<Key, T> &insert(const Key &key, const T &value);
 111
 112     /*!
 113      * Removes all of the elements from elements from the map.  This however
 114      * will not delete pointers if the mapped type is a pointer type.
 115      */
 116     Map<Key, T> &clear();
 117
 118     /*!
 119      * The number of elements in the map.
 120      *
 121      * \see isEmpty()
 122      */
 123     uint size() const;
 124
 125     /*!
 126      * Returns true if the map is empty.
 127      *
 128      * \see size()
 129      */
 130     bool isEmpty() const;
 131
 132     /*!
 133      * Find the first occurrence of \a key.
 134      */
 135     Iterator find(const Key &key);
 136
 137     /*!
 138      * Find the first occurrence of \a key.
 139      */
 140     ConstIterator find(const Key &key) const;
 141
 142     /*!
 143      * Returns true if the map contains an instance of \a key.
 144      */
 145     bool contains(const Key &key) const;
 146
 147     /*!
 148      * Erase the item at \a it from the list.
 149      */
 150     Map<Key, T> &erase(Iterator it);
 151
 152     /*!
 153      * Erase the item with \a key from the list.
 154      */
 155     Map<Key, T> &erase(const Key &key);
 156
 157     /*!
 158      * Returns a reference to the value associated with \a key.
 159      *
 160      * \note This has undefined behavior if the key is not present in the map.
 161      */
 162     const T &operator[](const Key &key) const;
 163
 164     /*!
 165      * Returns a reference to the value associated with \a key.
 166      *
 167      * \note This has undefined behavior if the key is not present in the map.
 168      */
 169     T &operator[](const Key &key);
 170
 171     /*!
 172      * Make a shallow, implicitly shared, copy of \a m.  Because this is
 173      * implicitly shared, this method is lightweight and suitable for
 174      * pass-by-value usage.
 175      */
 176     Map<Key, T> &operator=(const Map<Key, T> &m);
 177
 178   protected:
 179     /*
 180      * If this List is being shared via implicit sharing, do a deep copy of the
 181      * data and separate from the shared members.  This should be called by all
 182      * non-const subclass members.
 183      */
 184     void detach();
 185
 186   private:
 187 #ifndef DO_NOT_DOCUMENT
 188     template <class KeyP, class TP> class MapPrivate;
 189     MapPrivate<Key, T> *d;
 190 #endif
 191   };
 192
 193 }
 194
 195 // Since GCC doesn't support the "export" keyword, we have to include the
 196 // implementation.
 197
 198 #include "tmap.tcc"
 199
 200 #endif