hash_table.h File Reference

---

Detailed Description

A general purpose hash table.

This hash table module maps C strings to arbitrary objects (void pointers). For example, to store a file object using the pathname as a key:

struct hash_table *h;
h = hash_table_create(0,0);

FILE * file = fopen(pathname,"r");

hash_table_insert(h,pathname,file);
file = hash_table_remove(h,pathname);

To list all of the items in a hash table, use hash_table_firstkey and hash_table_nextkey like this:

char *key;
void *value;

hash_table_firstkey(h);

while(hash_table_nextkey(h,&key,&value)) {
	printf("table contains: %s\n",key);
}

Go to the source code of this file.

Typedefs
typedef unsigned(*	hash_func_t )(const char *key)
	The type signature for a hash function given to hash_table_create.
Functions
hash_table *	hash_table_create (int buckets, hash_func_t func)
	Create a new hash table.
void	hash_table_delete (struct hash_table *h)
	Delete a hash table.
int	hash_table_size (struct hash_table *h)
	Count the entries in a hash table.
int	hash_table_insert (struct hash_table *h, const char *key, const void *value)
	Insert a key and value.
void *	hash_table_lookup (struct hash_table *h, const char *key)
	Look up a value by key.
void *	hash_table_remove (struct hash_table *h, const char *key)
	Remove a value by key.
void	hash_table_firstkey (struct hash_table *h)
	Begin iteration over all keys.
int	hash_table_nextkey (struct hash_table *h, char **key, void **value)
	Continue iteration over all keys.
unsigned	hash_string (const char *s)
	A default hash function.

---

Typedef Documentation

typedef unsigned(* hash_func_t)(const char *key)

The type signature for a hash function given to hash_table_create.

---

Function Documentation

struct hash_table* hash_table_create (  int  buckets, hash_func_t  func )

Create a new hash table. Parameters: buckets  The number of buckets in the table. If zero, a default value will be used. func  The default hash function to be used. If zero, hash_string will be used. Returns: A pointer to a new hash table.

void hash_table_delete (  struct hash_table *  h  )

Delete a hash table. Note that this function will not delete all of the objects contained within the hash table. Parameters: h  The hash table to delete.

int hash_table_size (  struct hash_table *  h  )

Count the entries in a hash table. Returns: The number of entries in the table. Parameters: h  A pointer to a hash table.

int hash_table_insert (  struct hash_table *  h, const char *  key, const void *  value )

Insert a key and value. This call will fail if the table already contains the same key. You must call hash_table_remove to remove it. Also note that you cannot insert a null value into the table. Parameters: h  A pointer to a hash table. key  A pointer to a string key which will be hashed and duplicated. value  A pointer to store with the key. Returns: One if the insert succeeded, failure otherwise

void* hash_table_lookup (  struct hash_table *  h, const char *  key )

Look up a value by key. Parameters: h  A pointer to a hash table. key  A string key to search for. Returns: If found, the pointer associated with the key, otherwise null.

void* hash_table_remove (  struct hash_table *  h, const char *  key )

Remove a value by key. Parameters: h  A pointer to a hash table. key  A string key to remove. Returns: If found, the pointer associated with the key, otherwise null.

void hash_table_firstkey (  struct hash_table *  h  )

Begin iteration over all keys. This function begins a new iteration over a hash table, allowing you to visit every key and value in the table. Next, invoke hash_table_nextkey to retrieve each value in order. Parameters: h  A pointer to a hash table.

int hash_table_nextkey (  struct hash_table *  h, char **  key, void **  value )

Continue iteration over all keys. This function returns the next key and value in the iteration. Parameters: h  A pointer to a hash table. key  A pointer to a key pointer. value  A pointer to a value pointer. Returns: Zero if there are no more elements to visit, one otherwise.

unsigned hash_string (  const char *  s  )

A default hash function. Parameters: s  A string to hash. Returns: An integer hash of the string.

---