manpages

cp_hashtable(3)

cp_hashtable(3) libcprops - cp_hashtable cp_hashtable(3)

NAME

cp_hashtable - a general purpose hashtable implementation

DESCRIPTION

cp_hashtable is a general purpose hashtable implementation. Instances may be created with a specifiable degree of internal or external synchronization and entry memory management. It is also possible to specify the load factors controlling when internal table resizes occur.

INTERFACE

the following is a summary of functions provided by <cprops/hashtable.h>.

CONSTRUCTOR FUNCTIONS

cp_hashtable *cp_hashtable_create(unsigned long size_hint, cp_hashfunction hash_fn, cp_compare_fn compare_fn);
cp_hashtable *cp_hashtable_create_by_mode(int mode, int size_hint, cp_hashfunction hash_fn, cp_compare_fn compare_fn);
cp_hashtable * cp_hashtable_create_copy_mode(unsigned long size_hint, cp_hashfunction cp_hashfn, cp_compare_fn compare_fn, cp_copy_fn copy_key, cp_destructor_fn free_key); cp_copy_fn copy_value cp_destructor_fn free_value);
cp_hashtable * cp_hashtable_create_by_option(int mode, unsigned long size_hint, cp_hashfunction hash_fn, cp_compare_fn compare_fn, cp_copy_fn copy_key, cp_destructor_fn free_key); cp_copy_fn copy_value cp_destructor_fn free_value);

DESTRUCTOR FUNCTIONS

void cp_hashtable_destroy(cp_hashtable *table);
void cp_hashtable_destroy_shallow(cp_hashtable *table);
void cp_hashtable_destroy_deep(cp_hashtable *table);
void cp_hashtable_destroy_custom(cp_hashtable *table, cp_destructor_fn dk, cp_destructor_fn dv);

ITEM INSERTION

void *cp_hashtable_put(cp_hashtable *table, void *key, void *value);
void *cp_hashtable_put_by_option(cp_hashtable *table, void *key, void *value, int mode);
void *cp_hashtable_put_safe(cp_hashtable *table, void * key, void *value);
void *cp_hashtable_put_copy(cp_hashtable *table, void *key, void *value);

ITEM RETRIEVAL

void *cp_hashtable_get(cp_hashtable *table, void *key);
void *cp_hashtable_get_by_option(cp_hashtable *table, void *key, int mode);
void **cp_hashtable_get_keys(cp_hashtable *table);
void **cp_hashtable_get_values(cp_hashtable *table);
int cp_hashtable_contains(cp_hashtable *table, void *key);

ITEM REMOVAL

void *cp_hashtable_remove(cp_hashtable *table, void *key);
int cp_hashtable_remove_deep(cp_hashtable *table, void *key);
int cp_hashtable_remove_all(cp_hashtable *table);

BEHAVIOR

int cp_hashtable_set_mode(cp_hashtable *table, int mode);
int cp_hashtable_unset_mode(cp_hashtable *table, int mode);
int cp_hashtable_set_min_size(cp_hashtable *table, int size);
int cp_hashtable_set_min_fill_factor(cp_hashtable *table, int factor);
int cp_hashtable_set_max_fill_factor(cp_hashtable *table, int factor);

SYNCHRONIZATION

int cp_hashtable_lock(cp_hashtable *table, int type);
int cp_hashtable_unlock(cp_hashtable *table);
int cp_hashtable_rdlock(cp_hashtable *table);
int cp_hashtable_wrlock(cp_hashtable *table);

OTHER

unsigned long cp_hashtable_count(cp_hashtable *table);
cp_hashtable_is_empty(cp_hashtable *table);

HASH- and COMPARISON FUNCTIONS

libcprops provides the following hash function implementations for primitives and null terminated strings:

unsigned long cp_hash_char(void *key);


int cp_hash_compare_char(void *a, void *b);


unsigned long cp_hash_int(void *key);


int cp_hash_compare_int(void *a, void *b);


unsigned long cp_hash_long(void *key);


int cp_hash_compare_long(void *a, void *b);


unsigned long cp_hash_float(void *key);


int cp_hash_compare_float(void *a, void *b);


unsigned long cp_hash_double(void *key);


int cp_hash_compare_double(void *a, void *b);


unsigned long cp_hash_addr(void *key);


int cp_hash_compare_addr(void *a, void *b);


unsigned long cp_hash_string(void *key);


int cp_hash_compare_string(void *a, void *b);


unsigned long cp_hash_istring(void *key);


int cp_hash_compare_istring(void *a, void *b);

EXAMPLE

The following code creates a hashtable mapping names to phone numbers. The hash function used is cp_hash_istring, a case insensitive hash function for null terminated strings.

#include <stdio.h>
#include <string.h>		/* for strdup */
#include <strings.h>	/* for strcasecmp */
#include <stdlib.h>		/* for free */
#include <cprops/hashtable.h>
int main()
{


    cp_hashtable *t =


        cp_hashtable_create_by_option(COLLECTION_MODE_NOSYNC |


                                      COLLECTION_MODE_COPY |


                                      COLLECTION_MODE_DEEP,


                                      10,


                                      cp_hash_istring,


                                      (cp_compare_fn) strcasecmp,


                                      (cp_copy_fn) strdup,


                                      (cp_destructor_fn) free,


                                      (cp_copy_fn) strdup,


                                      (cp_destructor_fn) free);


    cp_hashtable_put(t, "ed", "123");


    cp_hashtable_put(t, "zed", "345");


    cp_hashtable_put(t, "fred", "789");


    while (1)


    {


        char name[80];


        char *number;


        printf("enter name [quit]: ");


        name[0] = '\0';


        fgets(name, 80, stdin);


        name[strlen(name) - 1] = '\0'; /* chop newline */


        if (name[0] == '\0') break;


        if ((number = cp_hashtable_get(t, name)) != NULL)


            printf("%s: %s\n", name, number);


        else


            printf("no entry for %s\n", name);


    }


    cp_hashtable_destroy(t);


    return 0;
}

for notes on compiling and linking see cprops(3).

SEE ALSO

cp_hashtable_create(3), cp_hashtable_destroy(3), cp_hashtable_get(3), cp_hashtable_put(3), cp_hashtable_lock(3), cp_hashtable_set_mode(3), cp_hashtable_contains(3), cp_hashtable_get_keys(3), cp_hashtable_count(3), cp_hashlist(3), cprops(3)

OCTOBER 2005 libcprops.0.0.3