man hash () - generic hash tables
NAME
hash_create, hash_destroy, hash_install, hash_lookup, hash_uninstall, hash_iter - generic hash tables
SYNOPSIS
#include <publib.h>
#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. If doit returns -1 or 0, hash_iter will stop the traversal and return the same value.
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 or 0, if doit returns either of those values, or 1 if it gets through all elements in the table.
SEE ALSO
AUTHOR
Lars Wirzenius (lars.wirzenius@helsinki.fi)