hash-table.h File Reference

Hash table. More...

Go to the source code of this file.

Data Structures
struct	_HashTablePair
struct	_HashTableIterator

Macros
#define	HASH_TABLE_NULL   ((void *) 0)

Typedefs
typedef struct _HashTable	HashTable
typedef struct _HashTableIterator	HashTableIterator
typedef struct _HashTableEntry	HashTableEntry
typedef void *	HashTableKey
typedef void *	HashTableValue
typedef struct _HashTablePair	HashTablePair
typedef unsigned int(*	HashTableHashFunc) (HashTableKey value)
typedef int(*	HashTableEqualFunc) (HashTableKey value1, HashTableKey value2)
typedef void(*	HashTableKeyFreeFunc) (HashTableKey value)
typedef void(*	HashTableValueFreeFunc) (HashTableValue value)

Functions
HashTable *	hash_table_new (HashTableHashFunc hash_func, HashTableEqualFunc equal_func)
void	hash_table_free (HashTable *hash_table)
void	hash_table_register_free_functions (HashTable *hash_table, HashTableKeyFreeFunc key_free_func, HashTableValueFreeFunc value_free_func)
int	hash_table_insert (HashTable *hash_table, HashTableKey key, HashTableValue value)
HashTableValue	hash_table_lookup (HashTable *hash_table, HashTableKey key)
int	hash_table_remove (HashTable *hash_table, HashTableKey key)
unsigned int	hash_table_num_entries (HashTable *hash_table)
void	hash_table_iterate (HashTable *hash_table, HashTableIterator *iter)
int	hash_table_iter_has_more (HashTableIterator *iterator)
HashTablePair	hash_table_iter_next (HashTableIterator *iterator)

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.

Macro Definition Documentation

HASH_TABLE_NULL

#define HASH_TABLE_NULL   ((void *) 0)

A null HashTableValue.

Typedef Documentation

HashTable

typedef struct _HashTable HashTable

A hash table structure.

HashTableEntry

typedef struct _HashTableEntry HashTableEntry

Internal structure representing an entry in a hash table.

HashTableEqualFunc

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.

HashTableHashFunc

typedef unsigned int(* 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.

HashTableIterator

typedef struct _HashTableIterator HashTableIterator

Structure used to iterate over a hash table.

HashTableKey

typedef void* HashTableKey

A key to look up a value in a HashTable.

HashTableKeyFreeFunc

typedef void(* HashTableKeyFreeFunc) (HashTableKey value)

Type of function used to free keys when entries are removed from a hash table.

HashTablePair

typedef struct _HashTablePair HashTablePair

Internal structure representing an entry in hash table used as HashTableIterator next result.

HashTableValue

typedef void* HashTableValue

A value stored in a HashTable.

HashTableValueFreeFunc

typedef void(* HashTableValueFreeFunc) (HashTableValue value)

Type of function used to free values when entries are removed from a hash table.

Function Documentation

hash_table_free()

void hash_table_free

(

HashTable *

hash_table

)

Destroy a hash table.

Parameters

hash_table

The hash table to destroy.

hash_table_insert()

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.

hash_table_iter_has_more()

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.

hash_table_iter_next()

HashTablePair hash_table_iter_next

(

HashTableIterator *

iterator

)

Using a hash table iterator, retrieve the next HashTablePair.

Note: To avoid HashTableEntry internal HashTablePair from being tampered with, and potentially messing with internal table structure, the function returns a copy of HashTablePair stored internally.

Parameters

iterator

The hash table iterator.

Returns

The next HashTablePair from the hash table, or HASH_TABLE_NULL of Key and Value if there are no more keys to iterate over.

hash_table_iterate()

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.

hash_table_lookup()

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.

hash_table_new()

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.

hash_table_num_entries()

unsigned 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.

hash_table_register_free_functions()

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.

hash_table_remove()

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.