wlgol/include/hashtable.h

#ifndef HASHTABLE_H
#define HASHTABLE_H

#include <stdbool.h>

struct htobj;
typedef struct htobj *hashtable;

typedef struct {
	struct htobj *h;
	struct entry *entry;
	int index;
} ht_iterator;

/**
 * @brief Create a new hashtable
 *
 * This function creates a new hashtable with the specified size.
 * It initializes the table with NULL entries.
 *
 * @param size The size of the hashtable
 * @return A pointer to the newly created hashtable
 */
hashtable hashtable_new(int size);

/**
 * @brief Insert a new key-value pair into the hashtable
 *
 * This function inserts a new key-value pair into the hashtable.
 * It calculates the index using the hash function and inserts the
 * key-value pair at the beginning of the linked list at that index.
 *
 * @param h Pointer to the hashtable
 * @param key Pointer to the key
 * @param value Pointer to the value
 * @return null or pointer to the previous value of the key
 */
void *hashtable_set(hashtable h, const char *key, void *value);

/**
 * @brief Get the value associated with a key from the hashtable
 *
 * This function takes a hashtable and a key as input and returns the
 * value associated with the key. If the key is not found in the
 * hashtable, it returns NULL.
 *
 * @param h Pointer to the hashtable
 * @param key Pointer to the key
 * @return Pointer to the value associated with the key, or NULL if not found
 */
void *hashtable_lookup(hashtable h, const char *key);

/**
 * @brief Remove a key-value pair from the hashtable
 *
 * This function removes a key-value pair from the hashtable.
 * It calculates the index using the hash function and traverses
 * the linked list at that index. If the key is found, it removes
 * the corresponding entry from the linked list and frees the memory.
 *
 * @param h Pointer to the hashtable
 * @param key Pointer to the key to remove
 * @return null or value associated with the removed key.
 */
void *hashtable_remove(hashtable h, const char *key);

/**
 * @brief Destroy hashtable.
 *
 * Values must be destroyed by the caller earlier.
 *
 * @param h Reference to the hastable.
 */
void hashtable_destroy(hashtable h);

/**
 * @brief Get the iterator of key-value pairs in the hashtable
 *
 * This function returns the iterator of key-value pairs in the hashtable.
 *
 * @param h Pointer to the hashtable
 * @return The iterator of key-value pairs in the hashtable
 */
ht_iterator hashtable_iter(hashtable h);

/**
 * @brief Get the next key-value pair from the iterator
 *
 * This function returns the next key-value pair from the iterator.
 *
 * @param iter Pointer to the iterator
 * @return true if there is a next key-value pair, false otherwise
 */
bool ht_iter_next(ht_iterator *iter);

/**
 * @brief Get the key from the iterator
 *
 * This function returns the key from the iterator.
 *
 * @param iter Pointer to the iterator
 * @return The key from the iterator
 */
const char *ht_iter_key(ht_iterator *iter);

/**
 * @brief Get the value from the iterator
 *
 * This function returns the value from the iterator.
 *
 * @param iter Pointer to the iterator
 * @return The value from the iterator
 */
void *ht_iter_value(ht_iterator *iter);

#endif