diff options
Diffstat (limited to 'include/bh/hashmap.h')
| -rwxr-xr-x | include/bh/hashmap.h | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/include/bh/hashmap.h b/include/bh/hashmap.h new file mode 100755 index 0000000..da89609 --- /dev/null +++ b/include/bh/hashmap.h @@ -0,0 +1,223 @@ +#ifndef BH_HASHMAP_H +#define BH_HASHMAP_H + + +#include "common.h" + + +typedef struct bh_hashmap_s bh_hashmap_t; + + +/** + * Creates the new hashmap handle. + * + * \param equal Comparision function + * \param hash Key hash function + * + * \return On success, returns hashmap handle. + * \return On failure, returns a null pointer. + */ +bh_hashmap_t *bh_hashmap_new(bh_equal_cb_t equal, + bh_hash_cb_t hash); + + +/** + * Destroys the hashmap. + * + * \param hashmap Hashmap handle + */ +void bh_hashmap_free(bh_hashmap_t *hashmap); + + +/** + * Clears the hashmap. + * + * \param hashmap Hashmap handle + */ +void bh_hashmap_clear(bh_hashmap_t *hashmap); + + +/** + * Reserves space in the hashmap. + * + * This function can both expand and shrink the available space in hashmap. + * This function takes into account current hashmap load factor. + * + * \param hashmap Hahsmap handle + * \param size Capacity + * + * \note Calling this function will invalidate iterators. + * \note Actual hashmap capacity can be bigger then requested. + * + * \return On success, returns zero value. + * \return On failure, returns error code. + */ +int bh_hashmap_reserve(bh_hashmap_t *hashmap, + size_t size); + + +/** + * Inserts the pair of key-value into the hashmap. + * + * \param hashmap Hashmap handle + * \param key Key + * \param value Value + * + * \note This function allows duplicates to be inserted. + * \note Calling this function will invalidate iterators. + * + * \return On success, returns zero value. + * \return On failure, returns error code. + */ +int bh_hashmap_insert(bh_hashmap_t *hashmap, + void *key, + void *value); + + +/** + * Removes value from the hashmap. + * + * \param hashmap Hashmap handle + * \param key Key + * + * \note Calling this function will invalidate iterators. + * \note If hashmap contains several elements with the same key, this function + * will remove only one key-value pair. + */ +void bh_hashmap_remove(bh_hashmap_t *hashmap, + void *key); + + +/** + * Returns value from the hashmap by key. + * + * \param hashmap Hashmap handle + * \param key Key + * \param value Value (optional) + * + * \return On success, returns zero value. + * \return On failure, returns error code. + */ +int bh_hashmap_at(bh_hashmap_t *hashmap, + void *key, + void **value); + + +/** + * Checks if the hashmap is empty. + * + * \param hashmap Hashmap handle + * + * \return If hashmap is empty, returns non-zero value + * \return If hashmap is not empty, returns zero value + */ +int bh_hashmap_empty(bh_hashmap_t *hashmap); + + +/** + * Returns the size of the hashmap. + * + * \param hashmap Hashmap handle + * + * \return Returns the size of the hashmap. + */ +size_t bh_hashmap_size(bh_hashmap_t *hashmap); + + +/** + * Returns the capacity of the hashmap. + * + * \param hashmap Hashmap handle + * + * \return Returns the capacity of the hashmap. + */ +size_t bh_hashmap_capacity(bh_hashmap_t *hashmap); + + +/** + * Returns the load factor of the hashmap. + * + * \param hashmap Hashmap handle + * + * \return Returns the load factor of the hashmap. + */ +float bh_hashmap_factor(bh_hashmap_t *hashmap); + + +/** + * Sets the load factor of the hashmap. + * + * \param hashmap Hashmap handle + * \param factor Load factor + * + * \note New load factor will be applied on the next reserve/insert operation. + */ +void bh_hashmap_set_factor(bh_hashmap_t *hashmap, + float factor); + + +/** + * Returns the iterator to the element in the hashmap with specified key. + * + * \param hashmap Hashmap handle + * \param iter Iterator + * + * \return On success, returns iterator value. + * \return On failure, returns NULL pointer. + * + * \note If hashmap contains several elements with the same key, this function + * will return iterator to one of them + */ +void *bh_hashmap_iter_at(bh_hashmap_t *hashmap, + void *key); + + +/** + * Returns the iterator to the next element in the hashmap. + * + * If the iterator is NULL pointer, this function will return iterator to the + * first element of the hashmap. + * + * \param hashmap Hashmap handle + * \param iter Iterator + * + * \return On success, returns new iterator value for the next element. + * \return On failure, returns NULL pointer. + */ +void *bh_hashmap_iter_next(bh_hashmap_t *hashmap, + void *iter); + + +/** + * Removes value from the hashmap pointed by by iterator. + * + * \param hashmap Hashmap handle + * \param iter Iterator + * + * \note Calling this function will invalidate iterators. + */ +void bh_hashmap_iter_remove(bh_hashmap_t *hashmap, + void *iter); + + +/** + * Returns key, pointed by the iterator. + * + * \param iter Iterator + * + * \return Returns key. + */ +void *bh_hashmap_iter_key(void *iter); + + +/** + * Returns value, pointed by the iterator. + * + * \param iter Iterator + * + * \return Returns value. + */ +void *bh_hashmap_iter_value(void *iter); + + +#endif /* BH_HASHMAP_H */ |