Map API

Libmodule offers an easy to use hashmap implementation, provided by <module/map.h> header.
It is used internally to store context’s modules and modules’ subscriptions/topics.

Structures

typedef enum {
    MAP_EPERM = -6,
    MAP_WRONG_PARAM,
    MAP_ERR,
    MAP_MISSING,
    MAP_FULL,
    MAP_OMEM,
    MAP_OK
} map_ret_code;

/* Callback for map_iterate */
typedef map_ret_code (*map_cb)(void *, const char *, void *);

/* Fn for map_set_dtor */
typedef void (*map_dtor)(void *);

/* Incomplete struct declaration for hashmap */
typedef struct _map map_t;

/* Incomplete struct declaration for hashmap iterator */
typedef struct _map_itr map_itr_t;

API

Where not specified, these functions return a map_ret_code.

map_new(const bool keysdup, const map_dtor fn)

Create a new map_t object.

Parameters:
  • keysdup (const bool) – whether keys lifetime should be managed by map
  • fn (const map_dtor) – callback called on value destroy. If NULL, values won’t be automatically destroyed.
Returns:

pointer to newly allocated map_t.
map_itr_new(m)

Create a new map iterator object. Note that it can be freed with free().

Parameters:
  • m (const map_t *) – pointer to map_t
Returns:

pointer to newly allocated map_itr_t.
map_itr_next(itr)

Get next iterator. If next iterator is past last element, iterator will be automatically freed.

Parameters:
  • itr (map_itr_t *) – pointer to map_itr_t
Returns:

pointer to next iterator.
map_itr_remove(itr)

Remove current iterator {key, value} from map.

Parameters:
  • itr (map_itr_t *) – pointer to map_itr_t
map_itr_get_key(itr)

Get current iterator’s key.

Parameters:
  • itr (const map_itr_t *) – pointer to map_itr_t
Returns:

current iterator’s key
map_itr_get_data(itr)

Get current iterator’s data.

Parameters:
  • itr (const map_itr_t *) – pointer to map_itr_t
Returns:

current iterator’s data
map_itr_set_data(itr)

Set current iterator’s data.

Parameters:
  • itr (const map_itr_t *) – pointer to map_itr_t
map_iterate(m, fn, userptr)

Iterate an hashmap calling cb on each element until MAP_OK is returned (or end of hashmap is reached). Returns MAP_MISSING if map is NULL or empty.
If fn() returns a value != MAP_OK, iteration will stop and: if value < MAP_OK, value will be returned, else MAP_OK will be returned.

Parameters:
  • m (map_t *) – pointer to map_t
  • fn (const map_cb) – callback to be called
  • userptr (void *) – userdata to be passed to callback as first parameter
map_put(m, key, val)

Put a value inside hashmap.
If key is already present, old value will be updated (and, if dtor is set, destroyed). Note that if new value and old value are the same pointer, nothing will be done.

Parameters:
  • m (map_t *) – pointer to map_t
  • key (const char *) – key for this value
  • val (void *) – value to be put inside map
map_get(m, key)

Get an hashmap value.

Parameters:
  • m (map_t *) – pointer to map_t
  • key (const char *) – key for this value
Returns:

void pointer to value, on NULL on error.
map_has_key(m, key)

Check if key exists in map.

Parameters:
  • m (map_t *) – pointer to map_t
  • key (const char *) – desired key
Returns:

true if key exists, false otherwise.
map_remove(m, key)

Remove a key from hashmap.

Parameters:
  • m (map_t *) – pointer to map_t
  • key (const char *) – key to be removed
map_clear(m)

Clears a map object by deleting any object inside map.

Parameters:
  • s (map_t *) – pointer to map_t
map_free(m)

Free a map object (it internally calls map_clear too).

Parameters:
  • m (map_t *) – pointer to map_t
map_length(m)

Get map length.

Parameters:
  • m (map_t *) – pointer to map_t
Returns:

map length or a map_ret_code if any error happens (map_t is null).