/******************************************************************************
 *
 * File:           hash.h
 *
 * Purpose:        Hash table header
 *
 * Author:         Jerry Coffin
 *
 * Description:    Public domain code by Jerry Coffin, with improvements by
 *                 HenkJan Wolthuis.
 *                 Date last modified: 05-Jul-1997
 *
 * Revisions:      18-09-2002 -- modified by Pavel Sakov
 *
 *****************************************************************************/

#ifndef _HASH_H
#define _HASH_H

struct hashtable;
typedef struct hashtable hashtable;

/** Copies a key. The key must be able to be deallocated by free().
 */
typedef void* (*ht_keycp) (void*);

/** Returns 1 if two keys are equal, 0 otherwise.
 */
typedef int (*ht_keyeq) (void*, void*);

/** Converts key to an unsigned integer (not necessarily unique).
 */
typedef unsigned int (*ht_key2hash) (void*);

/** Creates a hash table of specified size.
 *
 * @param size Size of hash table for output points
 * @param cp Key copy function
 * @param eq Key equality check function
 * @param hash Hash value calculation function
 */
hashtable* ht_create(int size, ht_keycp cp, ht_keyeq eq, ht_key2hash hash);

/** Create a hash table of specified size and key type.
 */
hashtable* ht_create_d1(int size);      /* double[1] */
hashtable* ht_create_d2(int size);      /* double[2] */
hashtable* ht_create_str(int size);     /* char* */

/** Destroys a hash table.
 * (Take care of deallocating data by ht_process() prior to destroying the
 * table if necessary.)
 *
 * @param table Hash table to be destroyed
 */
void ht_destroy(hashtable* table);

/** Inserts a new entry into the hash table.
 *
 * @param table The hash table
 * @param key Ponter to entry's key
 * @param data Pointer to associated data
 * @return Pointer to the old data associated with the key, NULL if the key
 *         wasn't in the table previously
 */
void* ht_insert(hashtable* table, void* key, void* data);

/** Returns a pointer to the data associated with a key.  If the key has
 * not been inserted in the table, returns NULL.
 *
 * @param table The hash table
 * @param key The key
 * @return The associated data or NULL
 */
void* ht_find(hashtable* table, void* key);

/** Deletes an entry from the table.  Returns a pointer to the data that
 * was associated with the key so that the calling code can dispose it
 * properly.
 *
 * @param table The hash table
 * @param key The key
 * @return The associated data or NULL
 */
void* ht_delete(hashtable* table, void* key);

/** For each entry, calls a specified function with corresponding data as a
 * parameter.
 *
 * @param table The hash table
 * @param func The action function
 */
void ht_process(hashtable* table, void (*func) (void*));

#endif                          /* _HASH_H */