1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
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. *
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. *
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 *
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 ***************************************************************************/
36 //! A generic, implicitly shared map.
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.
44 template <class Key, class T> class Map
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
57 typedef typename std::map<class Key, class T>::iterator Iterator;
58 typedef typename std::map<class Key, class T>::const_iterator ConstIterator;
60 typedef typename std::map<Key, T>::iterator Iterator;
61 typedef typename std::map<Key, T>::const_iterator ConstIterator;
66 * Constructs an empty Map.
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.
75 Map(const Map<Key, T> &m);
78 * Destroys this instance of the Map.
83 * Returns an STL style iterator to the beginning of the map. See
84 * std::map::iterator for the semantics.
89 * Returns an STL style iterator to the beginning of the map. See
90 * std::map::const_iterator for the semantics.
92 ConstIterator begin() const;
95 * Returns an STL style iterator to the end of the map. See
96 * std::map::iterator for the semantics.
101 * Returns an STL style iterator to the end of the map. See
102 * std::map::const_iterator for the semantics.
104 ConstIterator end() const;
107 * Inserts \a value under \a key in the map. If a value for \a key already
108 * exists it will be overwritten.
110 Map<Key, T> &insert(const Key &key, const T &value);
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.
116 Map<Key, T> &clear();
119 * The number of elements in the map.
126 * Returns true if the map is empty.
130 bool isEmpty() const;
133 * Find the first occurrence of \a key.
135 Iterator find(const Key &key);
138 * Find the first occurrence of \a key.
140 ConstIterator find(const Key &key) const;
143 * Returns true if the map contains an instance of \a key.
145 bool contains(const Key &key) const;
148 * Erase the item at \a it from the list.
150 Map<Key, T> &erase(Iterator it);
153 * Erase the item with \a key from the list.
155 Map<Key, T> &erase(const Key &key);
158 * Returns a reference to the value associated with \a key.
160 * \note This has undefined behavior if the key is not present in the map.
162 const T &operator[](const Key &key) const;
165 * Returns a reference to the value associated with \a key.
167 * \note This has undefined behavior if the key is not present in the map.
169 T &operator[](const Key &key);
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.
176 Map<Key, T> &operator=(const Map<Key, T> &m);
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.
187 #ifndef DO_NOT_DOCUMENT
188 template <class KeyP, class TP> class MapPrivate;
189 MapPrivate<Key, T> *d;
195 // Since GCC doesn't support the "export" keyword, we have to include the