hashmap(3m)

NAME
hashmap - a chaining hashmap

SYNOPSIS
#include <mba/hashmap.h>

HASHMAP_SMALL 17
HASHMAP_MEDIUM 701
HASHMAP_LARGE 8191

struct hashmap;

unsigned int hash_string(const void *s);

struct hashmap *hashmap_new(unsigned int size,
            unsigned int (*hash_fn)(const void *),
            void (*free_key_fnsize)(void *),
            void (*free_data_fn)(void *));
void hashmap_del(struct hashmap *h);

int hashmap_put(struct hashmap *h, void *key, void *data);
void *hashmap_get(const struct hashmap *h, const void *key);
int hashmap_is_empty(struct hashmap *h);
unsigned int hashmap_size(struct hashmap *h);
void hashmap_iterate(struct hashmap *h);
void *hashmap_next(struct hashmap *h);
void *hashmap_remove(struct hashmap *h, const void *key);

DESCRIPTION
A hashmap(3m) object associates keys with pointers to data objects. Large numbers of elements may be stored and retrieved efficiently.

It is vital that the free_key_fn and free_data_fn parameters are correct. If memory management of all keys and data is handled externally from the hashmap both function pointers must be NULL. There is only one appropriate pair of parameters for each scenario. Choosing incorrectly will result in a memory leak or undefined behavior.

Keys are only compared by their hash values. Keys that collide during a put will first be remove and called with free_key_fn on the existing key and free_data_fn on it's data pointer. For this reason hash functions must be chosen carefully. Please note, the hash_string function can return the same hash value for different strings in rare cases (e.g. the two character strings 'X"' and 'WA' both hash to the value 2762).

new Create a new hashmap. The maximum number of elements that can be stored in a hashmap is less than size * size. The macros HASHMAP_SMALL, HASHMAP_MEDIUM, and HASHMAP_LARGE are suitable size values (or choose 1/10th max elements and round up to prime number). The hash_fn parameter should be a pointer to a function that generates a unique integer value for each key to be stored in the hashmap. If the hash_fn parameter is NULL the key's address in memory will be used. The hash_string function is a suitable hash_fn for most strings. If the free_key_fn or free_data_fn parameters are not NULL they will be called with each key or data object that is removed from the map.

del Delete a hashmap. If the free_key_fn or free_data_fn functions are not NULL they will be called for each remaining element.

put Put a data pointer into the map by key. If an element with the same key already exists in the map and the free_key_fn or free_data_fn functions are not NULL the element will be removed and passed to the said functions.

get Retrieve a data pointer from the map by it's key.

is_empty
    Returns non-zero if the map is empty and 0 otherwise.

size
    Returns the number of data pointers in the map.

iterate, next
    Enumerate each key in the map. The iterate function positions the internal cursor to the beginning of the map. With each call to next, a key will be returned. When all keys have been enumerated, next will return NULL. Keys are not returned in any particular order.

remove
    Remove a data pointer from the map by it's key. If the free_key_fn function is not NULL it will be called on the key originally used to store the data pointer with put.

RETURNS

new The hashmap_new function returns a new struct hashmap * object that contains no elements.

put The hashmap_put function returns 0 and sets errno to indicate the nature of the error if the operation fails and non-zero otherwise.

get The hashmap_get function returns the data pointer being retrieved or NULL if the operation failed in which case errno is set appropriately.

size
    The hashmap_size function returns the number of data pointers in the map. If h is NULL, zero is returned.

next
    The hashmap_next function returns the next key in the map or NULL if all keys have been enumerated.

remove
    The hashmap_remove function returns the data pointer that was removed.