String mapΒΆ

String maps allow users to store elements based on a key-value pair. Whereas the value is an opaque pointer, keys are always defined as strings. This allows the use of a string hash function, such as DJB2. String maps are hash tables defined by the struct string_map data type.

The following functions can be used with a string map:

  • string_map_alloc: Allocate a new struct string_map instance. n determines the behavior of the map, where a larger value will make the lookups faster, but will require more memory even with an empty mapping. free_fn defines a user-provided callback that will free every value contained within the map. free_fn can be a null pointer if values inside the map must not be released when calling string_map_dealloc.

  • string_map_insert: Add an item into a string map. Returns zero on success; non-zero otherwise.

  • string_map_lookup: Finds an item inside the table with a given key. Returns a pointer to the item when successful; NULL otherwise.

  • string_map_forall: Iterate through all items inside the table and call a user-defined callback with an optional opaque pointer. Returns zero on success; non-zero otherwise. The user-defined callback must return zero on failure; when successful, it must return a negative number if the item must be removed, or a positive number otherwise.