diff options
Diffstat (limited to 'map.h')
| -rw-r--r-- | map.h | 83 |
1 files changed, 61 insertions, 22 deletions
@@ -3,44 +3,83 @@ #include <stdbool.h> +/** + * @file + * Crit-bit tree based map which supports unique prefix queries and + * ordered iteration. + */ + +/** Opaque map type. */ typedef struct Map Map; -/* Allocate a new map. */ +/** Allocate a new map. */ Map *map_new(void); -/* Retrieves a value, or NULL if it isn't in the map */ +/** Lookup a value, returns ``NULL`` if not found. */ void *map_get(const Map*, const char *key); -/* Get first element of the map, or NULL if empty */ +/** + * Get first element of the map, or ``NULL`` if empty. + * @param key Updated with the key of the first element. + */ void *map_first(const Map*, const char **key); -/* Returns the corresponding value if the given prefix is unique. - * Otherwise NULL, if no such prefix exists then errno is set to ENOENT. */ +/** + * Lookup element by unique prefix match. + * @param prefix The prefix to search for. + * @return The corresponding value, if the given prefix is unique. + * Otherwise ``NULL``. If no such prefix exists, then ``errno`` + * is set to ``ENOENT``. + */ void *map_closest(const Map*, const char *prefix); -/* check whether the map contains the given prefix, i.e. whether it can - * be extended to match a key of an element stored in the map. */ +/** + * Check whether the map contains the given prefix. + * whether it can be extended to match a key of a map element. + */ bool map_contains(const Map*, const char *prefix); -/* Test whether the given prefix can be extended to exactly one map element - * i.e. true iff the prefix map contains exactly one element. */ +/** + * Check whether the given prefix can be extended to exactly one map element. + * True iff the prefix map contains exactly one element. + */ bool map_leaf(const Map*, const char *prefix); -/* Place a member in the map. This returns false if we run out of memory - * (errno = ENOMEM), or if that key already appears in the map (errno = EEXIST). */ +/** + * Store a key value pair in the map. + * @return False if we run out of memory (``errno = ENOMEM``), or if the key + * already appears in the map (``errno = EEXIST``). + */ bool map_put(Map*, const char *key, const void *value); -/* Remove a member from the map. Returns the removed entry or NULL - * if there was no entry found using the given key*/ +/** + * Remove a map element. + * @return The removed entry or ``NULL`` if no such element exists. + */ void *map_delete(Map*, const char *key); -/* Copy all entries from `src' into `dest', overwrites existing entries in `dest' */ +/** Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``. */ bool map_copy(Map *dest, Map *src); -/* Ordered iteration over a map, call handle for every entry. If handle - * returns false, the iteration will stop. */ +/** + * Ordered iteration over a map. + * Invokes the passed callback for every map entry. + * If ``handle`` returns false, the iteration will stop. + * @param handle A function invoked for ever map element. + * @param data A context pointer, passed as last argument to ``handle``. + */ void map_iterate(const Map*, bool (*handle)(const char *key, void *value, void *data), const void *data); -/* Return a submap matching a prefix. This returns a pointer into the - * original map, so don't alter the map while using the return value. */ +/** + * Get a sub map matching a prefix. + * @rst + * .. warning:: This returns a pointer into the original map. + * Do not alter the map while using the return value. + * @endrst + */ const Map *map_prefix(const Map*, const char *prefix); -/* Test whether the map is empty i.e. contains no elements */ +/** Test whether the map is empty (contains no elements). */ bool map_empty(const Map*); -/* Remove every member from the map. The map will be empty after this. */ +/** Empty the map. */ void map_clear(Map*); -/* Release all memory associated with this map */ +/** Release all memory associated with this map. */ void map_free(Map*); -/* Call free(3) for every pointer stored in the map, then free the map itself */ +/** + * Call `free(3)` for every map element, then free the map itself. + * @rst + * .. warning:: Assumes map elements to be pointers. + * @endrst + */ void map_free_full(Map*); #endif |