cctools
Typedefs | Functions
hash_table.h File Reference

A general purpose hash table. More...

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

Functions

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

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);
}

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
bucketsThe number of buckets in the table. If zero, a default value will be used.
funcThe default hash function to be used. If zero, hash_string will be used.
Returns
A pointer to a new hash table.
void hash_table_clear ( struct hash_table *  h)

Remove all entries from an hash table.

Note that this function will not delete all of the objects contained within the hash table.

Parameters
hThe hash table to delete.
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
hThe 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
hA 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
hA pointer to a hash table.
keyA pointer to a string key which will be hashed and duplicated.
valueA 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
hA pointer to a hash table.
keyA 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
hA pointer to a hash table.
keyA 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
hA 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
hA pointer to a hash table.
keyA pointer to a key pointer.
valueA 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
sA string to hash.
Returns
An integer hash of the string.