map.h

   1 #ifndef MAP_H
   2 #define MAP_H
   3
   4 #include <stdbool.h>
   5
   6 typedef struct Map Map;
   7
   8 /* Allocate a new map. */
   9 Map *map_new(void);
  10 /* Retrieves a value, or NULL if it isn't in the map */
  11 void *map_get(const Map*, const char *key);
  12 /* Get first element of the map, or NULL if empty */
  13 void *map_first(const Map*, const char **key);
  14 /* Returns the corresponding value if the given prefix is unique.
  15  * Otherwise NULL, if no such prefix exists then errno is set to ENOENT. */
  16 void *map_closest(const Map*, const char *prefix);
  17 /* check whether the map contains the given prefix, i.e. whether it can
  18  * be extended to match a key of an element stored in the map. */
  19 bool map_contains(const Map*, const char *prefix);
  20 /* Test whether the given prefix can be extended to exactly one map element
  21  * i.e. true iff the prefix map contains exactly one element. */
  22 bool map_leaf(const Map*, const char *prefix);
  23 /* Place a member in the map. This returns false if we run out of memory
  24  * (errno = ENOMEM), or if that key already appears in the map (errno = EEXIST). */
  25 bool map_put(Map*, const char *key, const void *value);
  26 /* Remove a member from the map. Returns the removed entry or NULL
  27  * if there was no entry found using the given key*/
  28 void *map_delete(Map*, const char *key);
  29 /* Copy all entries from `src' into `dest', overwrites existing entries in `dest' */
  30 bool map_copy(Map *dest, Map *src);
  31 /* Ordered iteration over a map, call handle for every entry. If handle
  32  * returns false, the iteration will stop. */
  33 void map_iterate(const Map*, bool (*handle)(const char *key, void *value, void *data), const void *data);
  34 /* Return a submap matching a prefix. This returns a pointer into the
  35  * original map, so don't alter the map while using the return value. */
  36 const Map *map_prefix(const Map*, const char *prefix);
  37 /* Test whether the map is empty i.e. contains no elements */
  38 bool map_empty(const Map*);
  39 /* Remove every member from the map. The map will be empty after this. */
  40 void map_clear(Map*);
  41 /* Release all memory associated with this map */
  42 void map_free(Map*);
  43 /* Call free(3) for every pointer stored in the map, then free the map itself */
  44 void map_free_full(Map*);
  45
  46 #endif