hash.h File Reference

A hash table, which maps keys to values. More...

Go to the source code of this file.

Classes
struct	bucket
	internal data structure that holds a single key and value More...
struct	hash
	hash data structure that holds keys and values More...

Typedefs
typedef void(*	hash_remove_cb) (void *io_value)
	function prototype that is called to delete a value More...

Functions
int	hash_assign (struct hash *const o_hash, size_t const i_buckets, hash_remove_cb i_remove)
	initialize hash object More...
void	hash_discharge (struct hash *const io_hash)
	release resources held by the object More...
int	hash_insert (struct hash *const io_hash, char const *i_key, void *i_value)
	insert a key and value More...
void *	hash_lookup (int *const o_found, struct hash *const io_hash, char const *i_key)
	lookup a value More...
int	hash_remove (struct hash *const io_hash, char const *i_key)
	remove a key fromt the hash table More...

Detailed Description

A hash table, which maps keys to values.

Typedef Documentation

hash_remove_cb

void(* hash_remove_cb)(void *io_value)

function prototype that is called to delete a value

Parameters

[in]

io_value

value to delete

Returns

none

Function Documentation

hash_assign()

int hash_assign	(	struct hash *const	o_hash,
		size_t const	i_buckets,
		hash_remove_cb	i_remove
	)

initialize hash object

Parameters

[out]	o_hash	object to initialize
[in]	i_buckets	number of buckets the hash will hold
[in]	i_remove	function to remove values

Returns

0 success

ENOMEM memory allocation failed

This routine will allocate the buckets and can return a failure if there was not enough memory. Upon failure, it is not advisable to use the other routines. However, they should all exit gracefully with a valid error code.

If i_buckets is 0, the hash should not allow any operations to be performed.

hash_discharge()

void hash_discharge

(

struct hash *const

io_hash

)

release resources held by the object

Parameters

[in,out]

io_hash

object to release

Returns

none

hash_insert()

int hash_insert	(	struct hash *const	io_hash,
		char const *	i_key,
		void *	i_value
	)

insert a key and value

Parameters

[in,out]	io_hash	hash object
[in]	i_key	key to insert
[in,out]	i_value	value associated with key

Returns

0 success

EINVAL key is NULL

ENOMEM unable to allocate memory

hash_lookup()

void * hash_lookup	(	int *const	o_found,
		struct hash *const	io_hash,
		char const *	i_key
	)

lookup a value

Parameters

[out]	o_found	indicator if key exists
[in,out]	io_hash	hash object
[in]	i_key	key to find

Returns

value of key

Zero is a valid return value. Check o_found to see if the key exists.

hash_remove()

int hash_remove	(	struct hash *const	io_hash,
		char const *	i_key
	)

remove a key fromt the hash table

Parameters

[in]

i_key

key to remove

Returns

0 success

ENOENT key does not exist

If available, the routine will call hash_remove_cb to dispose of the key's value.