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  * Check whether the given prefix can be extended to exactly one map element.
  39  * True iff the prefix map contains exactly one element.
  40  */
  41 bool map_leaf(const Map*, const char *prefix);
  42 /**
  43  * Store a key value pair in the map.
  44  * @return False if we run out of memory (``errno = ENOMEM``), or if the key
  45  *         already appears in the map (``errno = EEXIST``).
  46  */
  47 bool map_put(Map*, const char *key, const void *value);
  48 /**
  49  * Remove a map element.
  50  * @return The removed entry or ``NULL`` if no such element exists.
  51  */
  52 void *map_delete(Map*, const char *key);
  53 /** Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``. */
  54 bool map_copy(Map *dest, Map *src);
  55 /**
  56  * Ordered iteration over a map.
  57  * Invokes the passed callback for every map entry.
  58  * If ``handle`` returns false, the iteration will stop.
  59  * @param handle A function invoked for ever map element.
  60  * @param data A context pointer, passed as last argument to ``handle``.
  61  */
  62 void map_iterate(const Map*, bool (*handle)(const char *key, void *value, void *data), const void *data);
  63 /**
  64  * Get a sub map matching a prefix.
  65  * @rst
  66  * .. warning:: This returns a pointer into the original map.
  67  *              Do not alter the map while using the return value.
  68  * @endrst
  69  */
  70 const Map *map_prefix(const Map*, const char *prefix);
  71 /** Test whether the map is empty (contains no elements). */
  72 bool map_empty(const Map*);
  73 /** Empty the map. */
  74 void map_clear(Map*);
  75 /** Release all memory associated with this map. */
  76 void map_free(Map*);
  77 /**
  78  * Call `free(3)` for every map element, then free the map itself.
  79  * @rst
  80  * .. warning:: Assumes map elements to be pointers.
  81  * @endrst
  82  */
  83 void map_free_full(Map*);
  84
  85 #endif