1 /* Abstract map data type as a C++ class. 2 Copyright (C) 2006-2021 Free Software Foundation, Inc. 3 Written by Bruno Haible <bruno@clisp.org>, 2018. 4 5 This program is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <https://www.gnu.org/licenses/>. */ 17 18 #ifndef _GL_MAP_HH 19 #define _GL_MAP_HH 20 21 #include "gl_map.h" 22 #include "gl_xmap.h" 23 24 #include <stdlib.h> /* because Gnulib's <stdlib.h> may '#define free ...' */ 25 26 /* gl_Map is a C++ wrapper around the gl_map data type. 27 Its key type is 'KEYTYPE *'. Its value type is 'VALUETYPE *'. 28 29 It is merely a pointer, not a smart pointer. In other words: 30 it does NOT do reference-counting, and the destructor does nothing. */ 31 32 template <class K, class V> class gl_Map; 33 34 template <class KEYTYPE, class VALUETYPE> 35 class gl_Map<KEYTYPE *, VALUETYPE *> 36 { 37 public: 38 // ------------------------------ Constructors ------------------------------ 39 40 gl_Map () 41 : _ptr (NULL) 42 {} 43 44 /* Creates an empty map. 45 IMPLEMENTATION is one of GL_ARRAY_MAP, GL_LINKEDHASH_MAP, GL_HASH_MAP. 46 EQUALS_FN is a key comparison function or NULL. 47 HASHCODE_FN is a key hash code function or NULL. 48 KDISPOSE_FN is a key disposal function or NULL. 49 VDISPOSE_FN is a value disposal function or NULL. */ 50 gl_Map (gl_map_implementation_t implementation, 51 bool (*equals_fn) (KEYTYPE * /*key1*/, KEYTYPE * /*key2*/), 52 size_t (*hashcode_fn) (KEYTYPE *), 53 void (*kdispose_fn) (KEYTYPE *), 54 void (*vdispose_fn) (VALUETYPE *)) 55 : _ptr (gl_map_create_empty (implementation, 56 reinterpret_cast<gl_mapkey_equals_fn>(equals_fn), 57 reinterpret_cast<gl_mapkey_hashcode_fn>(hashcode_fn), 58 reinterpret_cast<gl_mapkey_dispose_fn>(kdispose_fn), 59 reinterpret_cast<gl_mapvalue_dispose_fn>(vdispose_fn))) 60 {} 61 62 /* Copy constructor. */ 63 gl_Map (const gl_Map& x) 64 { _ptr = x._ptr; } 65 66 /* Assignment operator. */ 67 gl_Map& operator= (const gl_Map& x) 68 { _ptr = x._ptr; return *this; } 69 70 // ------------------------------- Destructor ------------------------------- 71 72 ~gl_Map () 73 { _ptr = NULL; } 74 75 // ----------------------- Read-only member functions ----------------------- 76 77 /* Returns the current number of pairs in the map. */ 78 size_t size () const 79 { return gl_map_size (_ptr); } 80 81 /* Searches whether a pair with the given key is already in the map. 82 Returns the value if found, or NULL if not present in the map. */ 83 VALUETYPE * get (KEYTYPE * key) const /* */ 84 { return static_cast<VALUETYPE *>(gl_map_get (_ptr, key)); } 85 86 /* Searches whether a pair with the given key is already in the map. 87 Returns true and sets VALUE to the value if found. 88 Returns false if not present in the map. */ 89 bool search (KEYTYPE * key, VALUETYPE *& value) const /* */ 90 { return gl_map_search (_ptr, key, &value); } 91 92 // ----------------------- Modifying member functions ----------------------- 93 94 /* Adds a pair to the map. 95 Returns true if a pair with the given key was not already in the map and so 96 this pair was added. 97 Returns false if a pair with the given key was already in the map and only 98 its value was replaced. */ 99 bool put (KEYTYPE * key, VALUETYPE * value) /* */ 100 { return gl_map_put (_ptr, key, value); } 101 102 /* Adds a pair to the map and retrieves the previous value. 103 Returns true if a pair with the given key was not already in the map and so 104 this pair was added. 105 Returns false and sets OLDVALUE to the previous value, if a pair with the 106 given key was already in the map and only its value was replaced. */ 107 bool getput (KEYTYPE * key, VALUETYPE * value, VALUETYPE *& oldvalue) /* */ 108 { return gl_map_getput (_ptr, key, value, &oldvalue); } 109 110 /* Removes a pair from the map. 111 Returns true if the key was found and its pair removed. 112 Returns false otherwise. */ 113 bool remove (KEYTYPE * key) /* */ 114 { return gl_map_remove (_ptr, key); } 115 116 /* Removes a pair from the map and retrieves the previous value. 117 Returns true and sets OLDVALUE to the previous value, if the key was found 118 and its pair removed. 119 Returns false otherwise. */ 120 bool getremove (KEYTYPE * key, VALUETYPE *& oldvalue) /* */ 121 { return gl_map_getremove (_ptr, key, &oldvalue); } 122 123 /* Frees the entire map. 124 (But this call does not free the keys and values of the pairs in the map. 125 It only invokes the KDISPOSE_FN on each key and the VDISPOSE_FN on each value 126 of the pairs in the map.) */ 127 void free () /* */ 128 { gl_map_free (_ptr); _ptr = NULL; } 129 130 // ------------------------------ Private stuff ------------------------------ 131 132 private: 133 gl_map_t _ptr; 134 135 public: 136 // -------------------------------- Iterators -------------------------------- 137 // Only a forward iterator. 138 // Does not implement the STL operations (++, *, and != .end()), but a simpler 139 // interface that needs only one virtual function call per iteration instead 140 // of three. 141 142 class iterator { 143 public: 144 145 /* If there is a next pair, stores the next pair in KEY and VALUE, advance 146 the iterator, and returns true. Otherwise, returns false. */ 147 bool next (KEYTYPE *& key, VALUETYPE *& value) /* */ 148 { 149 const void *next_key; 150 const void *next_value; 151 bool has_next = gl_map_iterator_next (&_state, &next_key, &next_value); 152 if (has_next) 153 { 154 key = static_cast<KEYTYPE *>(next_key); 155 value = static_cast<VALUETYPE *>(next_value); 156 } 157 return has_next; 158 } 159 160 ~iterator () 161 { gl_map_iterator_free (&_state); } 162 163 #if defined __xlC__ || defined __HP_aCC || defined __SUNPRO_CC 164 public: 165 #else 166 private: 167 friend iterator gl_Map::begin (); 168 #endif 169 170 iterator (gl_map_t ptr) 171 : _state (gl_map_iterator (ptr)) 172 {} 173 174 private: 175 176 gl_map_iterator_t _state; 177 }; 178 179 /* Creates an iterator traversing the map. 180 The map's contents must not be modified while the iterator is in use, 181 except for modifying the value of the last returned key or removing the 182 last returned pair. */ 183 iterator begin () /* */ 184 { return iterator (_ptr); } 185 }; 186 187 #endif /* _GL_MAP_HH */