#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 */