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