archeus/include/arc/std/hashtable.h

#ifndef ARC_STD_HASHTABLE_H_
#define ARC_STD_HASHTABLE_H_

#ifdef __cplusplus
extern "C" {
#endif

#include "arc/std/bool.h"
#include <stdint.h>

/**
 * @brief a hashing function ptr
 *
 * @param[in] key value to hash
 *
 * @return uint32_t hashed value of the tkey
*/
typedef uint32_t (* ARC_Hashtable_HashFn)(void *key);

/**
 * @brief the hashtable key comparison callback function
 *
 * @param[in] key1 first key
 * @param[in] key2 second key
 *
 * @return ARC_True when keys match
*/
typedef ARC_Bool (* ARC_Hashtable_KeyCompareFn)(void *key1, void *key2);

/**
 * @brief a callback that cleans up a key and value's memory when it is removed from the hashtable
 *
 * @param[in] data the key to destroy
*/
typedef void (* ARC_Hashtable_DestroyKeyValueFn)(void *key, void *value);

/**
 * @brief a callback to be used by ARC_Hashtable_RunIteration
 *
 * @param[in] key      a key at the current iteration
 * @param[in] value    a value that matches the key at the current iteration
 * @param[in] userData any data passed into the function that uses this callback to be used in this callback
*/
typedef void (* ARC_Hashtable_IteratorFn)(void *key, void *value, void *userData);

/**
 * @brief a resizable hashtable data type (will find next open slot before resizing)
*/
typedef struct ARC_Hashtable ARC_Hashtable;

/**
 * @brief cteates ARC_Hashtable type
 *
 * @note if the default hashing function is used (CRC32), then the key value needs to be a string or end in '\0'
 *
 * @param[out] hashtable         ARC_Hashtable to initialize
 * @param[in]  hashFn            a callback for a hashing function to be used, if set to NULL, CRC32 will be used
 * @param[in]  compareFn         a callback for checking keys, if set to NULL, addresses will be compared
 * @param[in]  destroyKeyValueFn a callback to free the key and value, if set to NULL, it will not free anything
*/
void ARC_Hashtable_Create(ARC_Hashtable **hashtable, ARC_Hashtable_HashFn *hashFn, ARC_Hashtable_KeyCompareFn *keyCompareFn, ARC_Hashtable_DestroyKeyValueFn *destroyKeyValueFn);

/**
 * @brief destroys an ARC_Hashtable
 *
 * @param[in] hashtable ARC_Hashtable to free
*/
void ARC_Hashtable_Destroy(ARC_Hashtable *hashtable);

/**
 * @brief adds a value at a key to hastable
 *
 * @note this will error if you add more than 4,294,967,295 items (the max value of an unsigned int 32)
 *
 * @param[in] hashtable ARC_Hashtable to add to
 * @param[in] key       key for node that is being added
 * @param[in] value     value for node that is being added
*/
void ARC_Hashtable_Add(ARC_Hashtable *hashtable, void *key, void *value);

/**
 * @brief removes value from hashtable at a given key
 *
 * @param[in] hashtable ARC_Hashtable to remove from
 * @param[in] key       key of data to remove from the hashtable
*/
void ARC_Hashtable_Remove(ARC_Hashtable *hashtable, void *key);

/**
 * @brief clears all values from a hashtable
 *
 * @param[in] hashtable ARC_Hashtable to clear
*/
void ARC_Hashtable_Clear(ARC_Hashtable *hashtable);

/**
 * @brief gets a value from hashtable by key
 *
 * @param[in] hashtable the hashtable to get the value from
 * @param[in] key       the key to match against for a value
 *
 * @return the value if there is a key match, otherwise NULL
*/
void *ARC_Hashtable_Get(ARC_Hashtable *hashtable, void *key);

/**
 * @brief gets the number of elements stored in the hashtable
 *
 * @param[in] hashtable the hashtable to get number of elements from
 *
 * @return the size of the vector
*/
uint32_t ARC_Hashtable_GetSize(ARC_Hashtable *hashtable);

/**
 * @brief iterates through a hashtable passing available key value pairs to a callback
 *
 * @param[in] hashtable  the hashtable to iterate through
 * @param[in] iteratorFn the callback which will can use the iterated key value pairs
 * @patam[in] userData   anything to be used within the ARC_Hashtable_IteratorFn callback, can be NULL
*/
void ARC_Hashtable_RunIteration(ARC_Hashtable *hashtable, ARC_Hashtable_IteratorFn iteratorFn, void *userData);

#ifdef __cplusplus
}
#endif

#endif //ARC_STD_HASHTABLE_H_