HTABLE(3)

NAME
htable - Hash table library

SYNOPSIS
#include <htable.h>

    typedef /* ... */ htable;
    typedef struct {
    	char *key;
    	void *data;
    } hpair;
    typedef unsigned long (*hfunc_t)(const char *data,
                                     unsigned long table_size);
    htable htable_new(void);
    htable htable_new_custom(unsigned long size);
    void   htable_delete(htable ht);
    void   htable_set_hash_func(htable ht, hfunc_t func);
    int    htable_store_key(htable ht, const char *key);
    int    htable_store_data(htable ht, const char *key, void *data);
    int    htable_store(htable ht, const char *key, void *data);
    int    htable_exists(htable ht, const char *key);
    void * htable_fetch(htable ht, const char *key);
    int    htable_remove(htable ht, const char *key);
    void   htable_dump(htable ht, FILE *fout);
    alist  htable_list(htable ht);

DESCRIPTION
The htable hash table library provides a generic-purpose hash table interface.

The library provides three types: htable, hpair, and hfunc_t. The htable type stores all the data contained into a hash table. The hpair type is used by the htable_list() function to store the hash table pairs. The hfunc_t type is used by the htable_set_hash_func() function to specify a new hashing function.

The htable_new() function allocates a new hash table with default size.

The htable_new_custom() function allocates a new hash table, with the specified size size.

The htable_delete() function deallocates the previously allocated hash table ht.

The htable_set_hash_func() function specifies a new hashing fuction for the hash table ht.

The htable_store_key() function stores the key key into the hash table ht, with an associated data set to NULL. If the key is already existing, the htable_store_key() function will return the value -1, otherwise 0.

The htable_store_data() function associates the data data with the key key. If the key does not existing into the hash table, the key/data pair will not be stored and the htable_store_data() function will return the value -1, otherwise 0.

The htable_store() function stores a key/data pair into the hash table ht. Existing key/data pair will be overwritten.

The htable_exists() function returns 1 if the specified key key exists in the hash table ht, 0 otherwise.

The htable_fetch() function returns the data associated to the specified key key. If the key does not exist or no data was associated with the key, a NULL value will be returned.

The htable_remove() function removes the specified key key from the hash table ht. The htable_remove() function returns 1 if the specified key key exists in the hash table ht, 0 otherwise.

The htable_dump() function dumps a user readable description of the hash table ht to the specified file fout. This is useful for debugging purposes.

The htable_list() function returns a new allocated (unsorted) list filled with all the pairs (of type hpair) defined in the hash table. After use, the list should be deallocated (but not the elements, because they belong to the hash table).

EXAMPLES
Creating a hash table with some keys:

    htable ht = htable_new();
    htable_store_key(ht, "key1");
    htable_store_key(ht, "key2");
    htable_store(ht, "key3", "key with data");
    htable_store_key(ht, "key4");
    htable_remove(ht, "key4");
    printf("key1: %d\n", htable_exists(ht, "key1"));
    printf("key2: %d\n", htable_exists(ht, "key2"));
    printf("key3: %d\n", htable_exists(ht, "key3"));
    printf("key4: %d\n", htable_exists(ht, "key4"));
    printf("key5: %d\n", htable_exists(ht, "key5"));
    printf("key3 data: %s\n", htable_fetch(ht, "key3"));
    htable_delete(ht);

Dumping a hash table:

    htable ht = htable_new();
    htable_store_key(ht, "key1");
    htable_store_key(ht, "key2");
    /* ... */
    htable_dump(ht, stdout);
    htable_delete(ht);

SEE ALSO
alist(3)

AUTHORS
Sandro Sigala <sandro@sigala.it>