cp_hashlist

Section: libcprops - cp_hashlist (3)
Updated: OCTOBER 2005
Index Return to Main Contents [view source]
 

NAME

cp_hashlist - a hashtable supporting insertion order conservation and quick iteration

 

DESCRIPTION

cp_hashlist may be viewed as a hashtable where nodes are inserted in a linked list to express their iteration order or equivalently, as a linked list where entries are keyed to permit random access lookups. Like cp_hashtable, this implementation makes it possible to specify the degree of internal or external synchronization and entry memory management as well as several performance tuning parameters - namely the load factor limits for internal table resizing.  

INTERFACE

<cprops/hashlist.h> defines the following functions:  

CONSTRUCTOR FUNCTIONS

cp_hashlist *cp_hashlist_create(int initial_size,
                                 cp_hashfunction hash_fn,
                                 cp_compare_fn compare_fn);

cp_hashlist *cp_hashlist_create_by_mode(int mode,
                                         long initial_size,
                                         cp_hashfunction hash_fn,
                                         cp_compare_fn compare_fn);

cp_hashlist *cp_hashlist_create_by_option(int mode, long initial_size,
                                           cp_hashfunction cp_hash_fn,
                                           cp_compare_fn compare_fn,
                                           cp_copy_fn copy_key,
                                           cp_destructor_fn key_free,
                                           cp_copy_fn copy_value
                                           cp_destructor_fn free_value);  

DESTRUCTOR FUNCTIONS

void cp_hashlist_destroy(cp_hashlist *list);

void cp_hashlist_destroy_by_option(cp_hashlist *list, int mode);

void cp_hashlist_destroy_custom(cp_hashlist *list,
                                 cp_destructor_fn dk,
                                 cp_destructor_fn dv);  

ADDING MAPPINGS

void *cp_hashlist_insert(cp_hashlist *list, void *key, void *value);
void *cp_hashlist_insert_by_option(cp_hashlist *list,
                                    void *key,
                                    void *value,
                                    int mode);
void *cp_hashlist_append(cp_hashlist *list, void *key, void *value);
void *cp_hashlist_append_by_option(cp_hashlist *list,
                                    void *key,
                                    void *value,
                                    int mode);
 

REMOVING MAPPINGS

void *cp_hashlist_remove(cp_hashlist *list, void *key);
void *cp_hashlist_remove_deep(cp_hashlist *list, void *key);
void *cp_hashlist_remove_by_option(cp_hashlist *list,
                                    void *key, int mode);
void *cp_hashlist_remove_head(cp_hashlist *list);
void *cp_hashlist_remove_head_by_option(cp_hashlist *list, int mode);
void *cp_hashlist_remove_tail(cp_hashlist *list);
void *cp_hashlist_remove_tail_by_option(cp_hashlist *list, int mode);
 

ITEM RETRIEVAL

void *cp_hashlist_get(cp_hashlist *list, void *key);
void *cp_hashlist_get_head(cp_hashlist *list);
void *cp_hashlist_get_tail(cp_hashlist *list);  

BEHAVIOR

int cp_hashlist_get_mode(cp_hashlist *list);
int cp_hashlist_set_mode(cp_hashlist *list, int mode);
int cp_hashlist_unset_mode(cp_hashlist *list, int mode);
int cp_hashlist_set_min_size(cp_hashlist *list, long size);
int cp_hashlist_set_min_fill_factor(cp_hashlist *list, int factor);
int cp_hashlist_set_max_fill_factor(cp_hashlist *list, int factor);  

SYNCHRONIZATION

int cp_hashlist_lock(cp_hashlist *list, int type);
int cp_hashlist_unlock(cp_hashlist *list);
int cp_hashlist_rdlock(cp_hashlist *list);
int cp_hashlist_wrlock(cp_hashlist *list);  

OTHER

int cp_hashlist_callback(cp_hashlist *list,
                          int (*cb)(void *key, void *value, void *id),
                          void *id);
long cp_hashlist_item_count(cp_hashlist *list);
int cp_hashlist_is_empty(cp_hashlist *list);

 

EXAMPLE

The following code creates a hashlist, inserts mappings, performs a lookup and prints the keys in reverse order.

#include <cprops/hashlist.h>
#include <stdio.h>
#include <string.h> /* strcmp and strdup */
#include <stdlib.h> /* free */
#include <errno.h>  /* perror */

int main(int argc, char *argv[])
{
        char key[32];
        char value[32];
        char *res;
        cp_hashlist *t;
        cp_hashlist_iterator *i;
        int j;

        t = cp_hashlist_create_by_option(COLLECTION_MODE_NOSYNC | 
                                      COLLECTION_MODE_DEEP |
                                      COLLECTION_MODE_COPY,
                                      10,
                                      cp_hash_string,
                                      (cp_compare_fn) strcmp,
                                      (cp_copy_fn) strdup,
                                      (cp_destructor_fn) free,
                                      (cp_copy_fn) strdup,
                                      (cp_destructor_fn) free);
        if (t == NULL)
        {
                perror(argv[0]);
                exit(1);
        }

        for (j = 0; j < 10; j++)
        {
                sprintf(key, "ENTRY (%d)", j);
                sprintf(value, "VALUE (%d)", j);
                if (cp_hashlist_insert(t, key, value) == NULL)
                {
                        perror(argv[0]);
                        exit(1);
                }
        }
        
        res = cp_hashlist_get(t, "ENTRY (5)");
        printf("looking up entry #5: %s\n", res ? res : "not found");

        printf("iterating over list values:\n");
        i = cp_hashlist_create_iterator(t, COLLECTION_LOCK_NONE);
        while ((res = cp_hashlist_iterator_next_value(i)))
                printf("\to\t%s\n", res);

        cp_hashlist_iterator_destroy(i);
        cp_hashlist_destroy(t);

        return 0;
}

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

 

SEE ALSO

cp_hashlist_iterator(3), cp_hashlist_create(3), cp_hashlist_destroy(3), cp_hashlist_get(3), cp_hashlist_insert(3), cp_hashlist_lock(3), cp_hashlist_set_mode(3), cp_hashtable(3), cprops(3)


 

Index

NAME
DESCRIPTION
INTERFACE
CONSTRUCTOR FUNCTIONS
DESTRUCTOR FUNCTIONS
ADDING MAPPINGS
REMOVING MAPPINGS
ITEM RETRIEVAL
BEHAVIOR
SYNCHRONIZATION
OTHER
EXAMPLE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 12:01:45 GMT, May 23, 2006