hash.h File Reference

A simple hashmap implementation. More...

Data Structures
struct	hash_entry_s
	This structure represents an entry within a hash table. More...
struct	hash_s
	This represents a hash table. More...

Typedefs
typedef struct hash_entry_s	HASH_ENTRY_T
	This structure represents an entry within a hash table.
typedef struct hash_s	HASH_T
	This represents a hash table.

Functions
HASH_T *	hash_new (const unsigned long slots)
	Create a new hashmap with the given number of slots.
HASH_T *	unsync_hash_new (const unsigned long slots)
	Create a new unsynchronized hashmap with the given number of slots.
void	hash_clear (HASH_T *hash, void(*key_free_fn)(void *), void(*val_free_fn)(void *))
	Clears all keys and values from a hashmap.
void	hash_free (HASH_T *hash, void(*key_free_fn)(void *), void(*val_free_fn)(void *))
	Frees memory (including keys) associated with a hashmap.
void *	hash_add (HASH_T *hash, const char *key, const void *val)
	Add a value to a hashmap with the given key.
void *	hash_del (HASH_T *hash, const char *key)
	Remove a value from the hashmap.
void *	hash_get (const HASH_T *hash, const char *key)
	Get a value from the hashmap.
char **	hash_keys (const HASH_T *hash)
	Obtains all keys currently in the hashmap.
HASH_T *	hash_dup (const HASH_T *src, void *(*dup_fn)(void *))
	Create a deep copy of a hashmap, where dup_fn() is the function used to duplicated the hash value.
HASH_T *	hash_dup_strval (const HASH_T *src)
	Create a deep copy of a hashmap, assuming that the values are NULL-terminated strings.

Detailed Description

A simple hashmap implementation.

Function Documentation

hash_add()

void * hash_add	(	HASH_T *	hash,
		const char *	key,
		const void *	val
	)

Add a value to a hashmap with the given key.

If the hashmap already contains the key, the value is replaced and the old value returned. In this case, the key in the hashmap is reused; you may need to free() the key that was passed.

Parameters

hash	The hashmap to which the key/value pair will be added.
key	The key under which to store the value.
val	The value stored under the key.

Return values

void *	If the key already exists in the hashmap the previous value is returned.
NULL	If the key cannot be found in the hashmap.

hash_clear()

void hash_clear	(	HASH_T *	hash,
		void(*)(void *)	key_free_fn,
		void(*)(void *)	val_free_fn
	)

Clears all keys and values from a hashmap.

Frees all the keys and values in a HASH_T, but does not free the hash itself.

Parameters

hash	The hashmap to be freed.
key_free_fn	A function to be used to free memory associated with the key, or NULL if the keys should not be freed.
val_free_fn	A function to be used to free memory associated with the value, or NULL if the values should not be freed.

hash_del()

void * hash_del	(	HASH_T *	hash,
		const char *	key
	)

Remove a value from the hashmap.

Parameters

hash	The hashmap from which the key/value pair will be removed.
key	The key for the entry which is to be removed.

Return values

void *	The value which was removed.
NULL	If the key was not found.

hash_dup()

HASH_T * hash_dup	(	const HASH_T *	src,
		void *(*)(void *)	dup_fn
	)

Create a deep copy of a hashmap, where dup_fn() is the function used to duplicated the hash value.

(Hash keys are assumed to be strings). hash_free should be called on the pointer when no longer needed.

Parameters

src	The hashmap to copy.
dup_fn	The function used to copy the hash value.

Returns

A copy of the hashmap.

hash_dup_strval()

HASH_T * hash_dup_strval

(

const HASH_T *

src

)

Create a deep copy of a hashmap, assuming that the values are NULL-terminated strings.

Parameters

src	The hashmap to copy.

Returns

A copy of the hashmap.

hash_free()

void hash_free	(	HASH_T *	hash,
		void(*)(void *)	key_free_fn,
		void(*)(void *)	val_free_fn
	)

Frees memory (including keys) associated with a hashmap.

This function can free all memory associated with a hashmap.

Parameters

hash	The hashmap to be freed.
key_free_fn	A function to be used to free memory associated with the key, or NULL if the keys should not be freed.
val_free_fn	A function to be used to free memory associated with the value, or NULL if the values should not be freed.

hash_get()

void * hash_get	(	const HASH_T *	hash,
		const char *	key
	)

Get a value from the hashmap.

Parameters

hash	The hashmap to be searched for the key.
key	The key for which the value is to be returned.

Return values

void *	The value in the hashmap associated with the key, or NULL if not found.
NULL	If the key was not found.

hash_keys()

char ** hash_keys

(

const HASH_T *

hash

)

Obtains all keys currently in the hashmap.

Parameters

hash	The hashmap to be inspected.

Returns

A NULL-terminated array of all keys in the hashmap. Call free() on the array when it is no longer required; keys are pointers to the value in the hash and should not be freed.

hash_new()

HASH_T * hash_new

(

const unsigned long

slots

)

Create a new hashmap with the given number of slots.

Parameters

slots

The number of slots available in the hashmap. Keys hash to a slot, and if a slot already contains a key which yields the same hash, it is chained to other entries in the bucket.

Return values

HASH_T *	Returns a pointer to a HASH_T structure.
NULL	If the hash cannot be created.

unsync_hash_new()

HASH_T * unsync_hash_new

(

const unsigned long

slots

)

Create a new unsynchronized hashmap with the given number of slots.

Parameters

slots

The number of slots available in the hashmap. Keys hash to a slot, and if a slot already contains a key which yields the same hash, it is chained to other entries in the bucket.

Return values

HASH_T *	Returns a pointer to a HASH_T structure.
NULL	If the hash cannot be created.