238 lines
6.4 KiB
C
238 lines
6.4 KiB
C
#ifndef BHLIB_HASHMAP_H
|
|
#define BHLIB_HASHMAP_H
|
|
|
|
#include <bh/bh.h>
|
|
|
|
typedef struct bh_hashmap_s bh_hashmap_t;
|
|
|
|
/**
|
|
* @brief Create new hashmap object.
|
|
*
|
|
* @param equal Function used for comparing keys
|
|
* @param hash Function used to calculate hash value of the key
|
|
*
|
|
* @return If the function succeeds, the return value is a pointer to the new
|
|
* hashmap object.
|
|
* @return If the function fails, the return value is NULL.
|
|
*
|
|
* @warning The quality of the supplied hash function will affect performance
|
|
* of the hashmap.
|
|
*
|
|
* @sa bh_hashmap_free, bh_hashmap_reserve, bh_hashmap_insert
|
|
*/
|
|
bh_hashmap_t *bh_hashmap_new(bh_equal_cb_t equal,
|
|
bh_hash_cb_t hash);
|
|
|
|
/**
|
|
* @brief Free hashmap object.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @sa bh_hashmap_clear
|
|
*/
|
|
void bh_hashmap_free(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Clear the hashmap.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @warning Clearing the hashmap does invalidate iterators.
|
|
*
|
|
* @sa bh_hashmap_remove
|
|
*/
|
|
void bh_hashmap_clear(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Reserve space for the specified amount of elements.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param size The amount of elements.
|
|
*
|
|
* @return If the function succeeds, the return value is zero.
|
|
* @return If the function fails, the return value is non-zero.
|
|
*
|
|
* @warning Reserving hashmap space does invalidate iterators.
|
|
*
|
|
* @sa bh_hashmap_capacity, bh_hashmap_insert
|
|
*/
|
|
int bh_hashmap_reserve(bh_hashmap_t *hashmap,
|
|
size_t size);
|
|
|
|
/**
|
|
* @brief Insert key/value into the hashmap.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param key Key
|
|
* @param value Value
|
|
*
|
|
* @return If the function succeeds, the return value is zero.
|
|
* @return If the function fails, the return value is non-zero.
|
|
*
|
|
* @warning Inserted element is owned by the caller of the function.
|
|
* @warning Inserting elements into the hashmap does invalidate iterators.
|
|
*
|
|
* @sa bbh_hashmap_remove, bh_hashmap_at
|
|
*/
|
|
int bh_hashmap_insert(bh_hashmap_t *hashmap,
|
|
void *key,
|
|
void *value);
|
|
|
|
/**
|
|
* @brief Remove element from the hashmap.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param key Key.
|
|
*
|
|
* @warning Removing elements from the hashmap does invalidate iterators.
|
|
*
|
|
* @sa bh_hashmap_insert, bh_hashmap_at
|
|
*/
|
|
void bh_hashmap_remove(bh_hashmap_t *hashmap,
|
|
void *key);
|
|
|
|
/**
|
|
* @brief Return element value by the key from the hashmap.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap.
|
|
* @param key Key.
|
|
* @param exists Pointer to the exists flag (optional).
|
|
*
|
|
* @return If the function succeeds, the return value is a valid pointer to
|
|
* the element value.
|
|
* @return If the function fails, the return value is NULL.
|
|
*
|
|
* @note If the hashmap does not contain any element with the key, the
|
|
* function will fail.
|
|
*
|
|
* @sa bh_hashmap_empty, bh_hashmap_insert
|
|
*/
|
|
void *bh_hashmap_at(bh_hashmap_t *hashmap,
|
|
void *key,
|
|
int *exists);
|
|
|
|
/**
|
|
* @brief Check if the hashmap is empty.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @return The return value is non-zero if the hashmap is empty, otherwise
|
|
* zero.
|
|
*
|
|
* @sa bh_hashmap_size
|
|
*/
|
|
int bh_hashmap_empty(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Return hashmap size.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @return The return value is current hashmap size.
|
|
*
|
|
* @sa bh_hashmap_empty, bh_hashmap_capacity
|
|
*/
|
|
size_t bh_hashmap_size(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Return hashmap capacity.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @return The return value is current hashmap capacity.
|
|
*
|
|
* @sa bh_hashmap_reserve, bh_hashmap_size
|
|
*/
|
|
size_t bh_hashmap_capacity(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Return hashmap load factor.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
*
|
|
* @return The return value is current hashmap load factor.
|
|
*
|
|
* @sa bh_hashmap_set_factor, bh_hashmap_capacity
|
|
*/
|
|
float bh_hashmap_factor(bh_hashmap_t *hashmap);
|
|
|
|
/**
|
|
* @brief Set hashmap load factor.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param factor Load factor.
|
|
*
|
|
* @sa bh_hashmap_factor
|
|
*/
|
|
void bh_hashmap_set_factor(bh_hashmap_t *hashmap,
|
|
float factor);
|
|
|
|
/**
|
|
* @brief Return iterator for the element by the key.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param key Key
|
|
*
|
|
* @return The return value is the valid iterator for the element in the
|
|
* hashmap.
|
|
* @return The return value is the NULL iterator if there is no element with
|
|
* specified key.
|
|
*
|
|
* @sa bh_hashmap_iter_key, bh_hashmap_iter_value
|
|
*/
|
|
void *bh_hashmap_iter_at(bh_hashmap_t *hashmap,
|
|
void *key);
|
|
|
|
/**
|
|
* @brief Return iterator for the next element in the hashmap.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param iter Valid or NULL iterator.
|
|
*
|
|
* @return The return value is the valid iterator for the next element in the
|
|
* hashmap.
|
|
* @return The return value is the NULL iterator if there is no more elements
|
|
* in the hashmap.
|
|
*
|
|
* @sa bh_hashmap_iter_key, bh_hashmap_iter_value
|
|
*/
|
|
void *bh_hashmap_iter_next(bh_hashmap_t *hashmap,
|
|
void *iter);
|
|
|
|
/**
|
|
* @brief Remove element from the hashmap by the iterator.
|
|
*
|
|
* @param hashmap Valid pointer to the hashmap object.
|
|
* @param key Valid iterator.
|
|
*
|
|
* @warning Removing elements from the hashmap does invalidate iterators.
|
|
*
|
|
* @sa bh_hashmap_insert, bh_hashmap_at
|
|
*/
|
|
void bh_hashmap_iter_remove(bh_hashmap_t *hashmap,
|
|
void *iter);
|
|
|
|
/**
|
|
* @brief Return pointer to the element's key.
|
|
*
|
|
* @param iter Valid iterator.
|
|
*
|
|
* @return The return value is the stored element key.
|
|
*
|
|
* @sa bh_hashmap_iter_value, bh_hashmap_iter_next
|
|
*/
|
|
void *bh_hashmap_iter_key(void *iter);
|
|
|
|
/**
|
|
* @brief Return pointer to the element's value.
|
|
*
|
|
* @param iter Valid iterator.
|
|
*
|
|
* @return The return value is the stored element value.
|
|
*
|
|
* @sa bh_hashmap_iter_key, bh_hashmap_iter_next
|
|
*/
|
|
void *bh_hashmap_iter_value(void *iter);
|
|
|
|
#endif /* BHLIB_HASHMAP_H */
|