hash-table.h File Reference

Hash table. More...

Data Structures
struct	_HashTableIterator
	Definition of a HashTableIterator. More...
Defines
#define	HASH_TABLE_NULL   ((void *) 0)
	A null HashTableValue.
Typedefs
typedef struct _HashTable	HashTable
	A hash table structure.
typedef struct _HashTableIterator	HashTableIterator
	Structure used to iterate over a hash table.
typedef struct _HashTableEntry	HashTableEntry
	Internal structure representing an entry in a hash table.
typedef void *	HashTableKey
	A key to look up a value in a HashTable.
typedef void *	HashTableValue
	A value stored in a HashTable.
typedef unsigned long(*	HashTableHashFunc )(HashTableKey value)
	Hash function used to generate hash values for keys used in a hash table.
typedef int(*	HashTableEqualFunc )(HashTableKey value1, HashTableKey value2)
	Function used to compare two keys for equality.
typedef void(*	HashTableKeyFreeFunc )(HashTableKey value)
	Type of function used to free keys when entries are removed from a hash table.
typedef void(*	HashTableValueFreeFunc )(HashTableValue value)
	Type of function used to free values when entries are removed from a hash table.
Functions
HashTable *	hash_table_new (HashTableHashFunc hash_func, HashTableEqualFunc equal_func)
	Create a new hash table.
void	hash_table_free (HashTable *hash_table)
	Destroy a hash table.
void	hash_table_register_free_functions (HashTable *hash_table, HashTableKeyFreeFunc key_free_func, HashTableValueFreeFunc value_free_func)
	Register functions used to free the key and value when an entry is removed from a hash table.
int	hash_table_insert (HashTable *hash_table, HashTableKey key, HashTableValue value)
	Insert a value into a hash table, overwriting any existing entry using the same key.
HashTableValue	hash_table_lookup (HashTable *hash_table, HashTableKey key)
	Look up a value in a hash table by key.
int	hash_table_remove (HashTable *hash_table, HashTableKey key)
	Remove a value from a hash table.
int	hash_table_num_entries (HashTable *hash_table)
	Retrieve the number of entries in a hash table.
void	hash_table_iterate (HashTable *hash_table, HashTableIterator *iter)
	Initialise a HashTableIterator to iterate over a hash table.
int	hash_table_iter_has_more (HashTableIterator *iterator)
	Determine if there are more keys in the hash table to iterate over.
HashTableValue	hash_table_iter_next (HashTableIterator *iterator)
	Using a hash table iterator, retrieve the next key.

---

Detailed Description

Hash table.

A hash table stores a set of values which can be addressed by a key. Given the key, the corresponding value can be looked up quickly.

To create a hash table, use hash_table_new. To destroy a hash table, use hash_table_free.

To insert a value into a hash table, use hash_table_insert.

To remove a value from a hash table, use hash_table_remove.

To look up a value by its key, use hash_table_lookup.

To iterate over all values in a hash table, use hash_table_iterate to initialise a HashTableIterator structure. Each value can then be read in turn using hash_table_iter_next and hash_table_iter_has_more.

---

Typedef Documentation

typedef int(* HashTableEqualFunc)(HashTableKey value1, HashTableKey value2)

Function used to compare two keys for equality.

Returns:

Non-zero if the two keys are equal, zero if the keys are not equal.

typedef unsigned long(* HashTableHashFunc)(HashTableKey value)

Hash function used to generate hash values for keys used in a hash table.

Parameters:

value

The value to generate a hash value for.

Returns:

The hash value.

---

Function Documentation

void hash_table_free

(

HashTable *

hash_table

)

Destroy a hash table.

Parameters:

hash_table

The hash table to destroy.

int hash_table_insert	(	HashTable *	hash_table,
		HashTableKey	key,
		HashTableValue	value
	)

Insert a value into a hash table, overwriting any existing entry using the same key.

Parameters:

	hash_table	The hash table.
	key	The key for the new value.
	value	The value to insert.

Returns:

Non-zero if the value was added successfully, or zero if it was not possible to allocate memory for the new entry.

int hash_table_iter_has_more

(

HashTableIterator *

iterator

)

Determine if there are more keys in the hash table to iterate over.

Parameters:

iterator

The hash table iterator.

Returns:

Zero if there are no more values to iterate over, non-zero if there are more values to iterate over.

HashTableValue hash_table_iter_next

(

HashTableIterator *

iterator

)

Using a hash table iterator, retrieve the next key.

Parameters:

iterator

The hash table iterator.

Returns:

The next key from the hash table, or HASH_TABLE_NULL if there are no more keys to iterate over.

void hash_table_iterate	(	HashTable *	hash_table,
		HashTableIterator *	iter
	)

Initialise a HashTableIterator to iterate over a hash table.

Parameters:

	hash_table	The hash table.
	iter	Pointer to an iterator structure to initialise.

HashTableValue hash_table_lookup	(	HashTable *	hash_table,
		HashTableKey	key
	)

Look up a value in a hash table by key.

Parameters:

	hash_table	The hash table.
	key	The key of the value to look up.

Returns:

The value, or HASH_TABLE_NULL if there is no value with that key in the hash table.

HashTable* hash_table_new	(	HashTableHashFunc	hash_func,
		HashTableEqualFunc	equal_func
	)

Create a new hash table.

Parameters:

	hash_func	Function used to generate hash keys for the keys used in the table.
	equal_func	Function used to test keys used in the table for equality.

Returns:

A new hash table structure, or NULL if it was not possible to allocate the new hash table.

int hash_table_num_entries

(

HashTable *

hash_table

)

Retrieve the number of entries in a hash table.

Parameters:

hash_table

The hash table.

Returns:

The number of entries in the hash table.

void hash_table_register_free_functions	(	HashTable *	hash_table,
		HashTableKeyFreeFunc	key_free_func,
		HashTableValueFreeFunc	value_free_func
	)

Register functions used to free the key and value when an entry is removed from a hash table.

Parameters:

	hash_table	The hash table.
	key_free_func	Function used to free keys.
	value_free_func	Function used to free values.

int hash_table_remove	(	HashTable *	hash_table,
		HashTableKey	key
	)

Remove a value from a hash table.

Parameters:

	hash_table	The hash table.
	key	The key of the value to remove.

Returns:

Non-zero if a key was removed, or zero if the specified key was not found in the hash table.