vis

a vi-like editor based on Plan 9's structural regular expressions
map.h

(3372B)
      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 /**
     18  * Lookup a value, returns ``NULL`` if not found.
     19  * @param map The map to search within.
     20  * @param key The key to look up.
     21  */
     22 void *map_get(const Map *map, const char *key);
     23 /**
     24  * Get first element of the map, or ``NULL`` if empty.
     25  * @param map The map to query.
     26  * @param key Updated with the key of the first element.
     27  */
     28 void *map_first(const Map *map, const char **key);
     29 /**
     30  * Lookup element by unique prefix match.
     31  * @param map The map to search within.
     32  * @param prefix The prefix to search for.
     33  * @return The corresponding value, if the given prefix is unique.
     34  * Otherwise ``NULL``. If no such prefix exists, then ``errno``
     35  * is set to ``ENOENT``.
     36  */
     37 void *map_closest(const Map *map, const char *prefix);
     38 /**
     39  * Check whether the map contains the given prefix, or
     40  * whether it can be extended to match a key of a map element.
     41  * @param map The map to check.
     42  * @param prefix The prefix to search for.
     43  */
     44 bool map_contains(const Map *map, const char *prefix);
     45 /**
     46  * Store a key value pair in the map.
     47  * @param map The map to store the key-value pair in.
     48  * @param key The key to store.
     49  * @param value The value associated with the key.
     50  * @return False if we run out of memory (``errno = ENOMEM``), or if the key
     51  * already appears in the map (``errno = EEXIST``).
     52  */
     53 bool map_put(Map *map, const char *key, const void *value);
     54 /**
     55  * Remove a map element.
     56  * @param map The map to remove the element from.
     57  * @param key The key of the element to remove.
     58  * @return The removed entry or ``NULL`` if no such element exists.
     59  */
     60 void *map_delete(Map *map, const char *key);
     61 /**
     62  * Copy all entries from ``src`` into ``dest``, overwrites existing entries in ``dest``.
     63  * @param dest The destination map.
     64  * @param src The source map.
     65  */
     66 bool map_copy(Map *dest, Map *src);
     67 /**
     68  * Ordered iteration over a map.
     69  * Invokes the passed callback for every map entry.
     70  * If ``handle`` returns false, the iteration will stop.
     71  * @param map The map to iterate over.
     72  * @param handle A function invoked for every map element.
     73  * @param data A context pointer, passed as last argument to ``handle``.
     74  */
     75 void map_iterate(const Map *map, bool (*handle)(const char *key, void *value, void *data), const void *data);
     76 /**
     77  * Get a sub map matching a prefix.
     78  * @param map The map to get the sub-map from.
     79  * @param prefix The prefix to match.
     80  * @rst
     81  * .. warning:: This returns a pointer into the original map.
     82  * Do not alter the map while using the return value.
     83  * @endrst
     84  */
     85 const Map *map_prefix(const Map *map, const char *prefix);
     86 /**
     87  * Test whether the map is empty (contains no elements).
     88  * @param map The map to check.
     89  */
     90 bool map_empty(const Map *map);
     91 /**
     92  * Empty the map.
     93  * @param map The map to clear.
     94  */
     95 void map_clear(Map *map);
     96 /**
     97  * Release all memory associated with this map.
     98  * @param map The map to free.
     99  */
    100 void map_free(Map *map);
    101 /**
    102  * Call `free(3)` for every map element, then free the map itself.
    103  * @param map The map to free its elements and itself.
    104  * @rst
    105  * .. warning:: Assumes map elements to be pointers.
    106  * @endrst
    107  */
    108 void map_free_full(Map *map);
    109 
    110 #endif