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_MAP_H
27#define TAGLIB_MAP_H
28
29#include <map>
30
31#include "taglib.h"
32
33namespace 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 protected:
178 /*
179 * If this List is being shared via implicit sharing, do a deep copy of the
180 * data and separate from the shared members. This should be called by all
181 * non-const subclass members.
182 */
183 void detach();
184
185 private:
186#ifndef DO_NOT_DOCUMENT
187 template <class KeyP, class TP> class MapPrivate;
188 MapPrivate<Key, T> *d;
189#endif
190 };
191
192}
193
194// Since GCC doesn't support the "export" keyword, we have to include the
195// implementation.
196
197#include "tmap.tcc"
198
199#endif
200