NAME

       hash_create, hash_destroy, hash_install, hash_lookup, hash_uninstall, hash_iter - generic hash tables

SYNOPSIS

       #include <publib.h>

       Hashtab *hash_create(unsigned long (*fun)(void *),
                int (*cmp)(const void *, const void *));
       void hash_destroy(Hashtab *ht);
       void *hash_install(Hashtab *ht, void *data, size_t size);
       void *hash_lookup(Hashtab *ht, void *data);
       int hash_uninstall(Hashtab *ht, void *data);
       int hash_iter(Hashtab *ht, int (*doit)(void *, void *), void *param);

DESCRIPTION

       These  functions  implement  generic  hash  tables.  The table is created by hash_create and destroyed by
       hash_destroy.  The fun argument is a pointer to the hashing function, which must convert a  datum  to  an
       unsigned  long,  which  is  then  converted  to  an index into the hashing table.  cmp is a qsort(3)-like
       comparison functions, used to compare to (wannabe) hash table elements.

       hash_install installs a new datum into the table.  A pointer to the data and the size  of  the  data  are
       given  as  the  arguments.  If the size is 0, only the pointer value is copied to the table.  Otherwise a
       copy of the data is made into dynamically allocated memory.

       hash_lookup attempts to find a datum in the hash table.  A pointer to  another  datum  is  given  as  the
       argument.   The comparison function should compare equal (return 0) the desired datum and this datum (but
       the argument needn't be a fully initialized datum, although that is up to the writer  of  the  comparison
       function).   There  cannot  be  two  elements  in  the hash table that are equal (the comparison function
       returns 0 for them).  It is up to the user to handle collisions.

       hash_uninstall removes an element from a table.  The argument is a pointer to a datum that identifies the
       element.

       hash_iter  goes  through every element in the hash table and calls the doit function for each.  The first
       argument it provides to doit is the element in question, the second is whatever was given to hash_iter as
       param.   If doit returns -1 or 0 for any element in the hash table, hash_iter immediately returns without
       going through the remaining elements in the hash table.  Any other return value from doit is ignored.

RETURNS

       hash_create returns a pointer to the new hash table, or NULL if it fails.

       hash_install returns a pointer to an element in the table (either the installed  one,  or  one  that  was
       already installed, if one tries to install the same datum twice).

       hash_uninstall returns 0 if it found the element in the array, or -1 if it didn't.

       hash_lookup return a pointer to the element it finds, or NULL if it doesn't find anything beautiful.

       hash_iter  returns  -1,  0,  or 1.  If hash_iter receives a return value of -1 or 0 for some element from
       doit, hash_iter immediately returns -1 or 0, respectively.  In all other cases hash_iter returns 1.

SEE ALSO

       publib(3), qsort(3), bsearch(3)

AUTHOR

       Lars Wirzenius (lars.wirzenius@helsinki.fi)