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)