map.h

   1 #ifndef MAP_H
   2 #define MAP_H
   3
   4 #include <stdbool.h>
   5
   6 /**
   7  * @file
   8  * Crit-bit tree based map which supports unique prefix queries and
   9  * ordered iteration.
  10  */
  11
  12 /** Opaque map type. */
  13 typedef struct Map Map;
  14
  15 /** Allocate a new map. */
  16 Map *map_new(void);
  17 /** Lookup a value, returns ``NULL`` if not found. */
  18 void *map_get(const Map*, const char *key);
  19 /**
  20  * Get first element of the map, or ``NULL`` if empty.
  21  * @param key Updated with the key of the first element.
  22  */
  23 void *map_first(const Map*, const char **key);
  24 /**
  25  * Lookup element by unique prefix match.
  26  * @param prefix The prefix to search for.
  27  * @return The corresponding value, if the given prefix is unique.
  28  *         Otherwise ``NULL``. If no such prefix exists, then ``errno``
  29  *         is set to ``ENOENT``.
  30  */
  31 void *map_closest(const Map*, const char *prefix);
  32 /**
  33  * Check whether the map contains the given prefix.
  34  * whether it can be extended to match a key of a map element.
  35  */
  36 bool map_contains(const Map*, const char *prefix);
  37 /**
  38  * Store a key value pair in the map.
  39  * @return False if we run out of memory (``errno = ENOMEM``), or if the key
  40  *         already appears in the map (``errno = EEXIST``).
  41  */
  42 bool map_put(Map*, const char *key, const void *value);
  43 /**
  44  * Remove a map element.
  45  * @return The removed entry or ``NULL`` if no such element exists.
  46  */
  47 void *map_delete(Map*, const char *key);
  48 /** Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``. */
  49 bool map_copy(Map *dest, Map *src);
  50 /**
  51  * Ordered iteration over a map.
  52  * Invokes the passed callback for every map entry.
  53  * If ``handle`` returns false, the iteration will stop.
  54  * @param handle A function invoked for ever map element.
  55  * @param data A context pointer, passed as last argument to ``handle``.
  56  */
  57 void map_iterate(const Map*, bool (*handle)(const char *key, void *value, void *data), const void *data);
  58 /**
  59  * Get a sub map matching a prefix.
  60  * @rst
  61  * .. warning:: This returns a pointer into the original map.
  62  *              Do not alter the map while using the return value.
  63  * @endrst
  64  */
  65 const Map *map_prefix(const Map*, const char *prefix);
  66 /** Test whether the map is empty (contains no elements). */
  67 bool map_empty(const Map*);
  68 /** Empty the map. */
  69 void map_clear(Map*);
  70 /** Release all memory associated with this map. */
  71 void map_free(Map*);
  72 /**
  73  * Call `free(3)` for every map element, then free the map itself.
  74  * @rst
  75  * .. warning:: Assumes map elements to be pointers.
  76  * @endrst
  77  */
  78 void map_free_full(Map*);
  79
  80 #endif