lib/gl_map.hh

   1 /* Abstract map data type as a C++ class.
   2    Copyright (C) 2006-2024 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 */