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.

Functions

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

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 
) [read]

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.
Generated on Sun Aug 14 20:55:54 2011 for cctools by  doxygen 1.6.3