HSEARCH - enter or find item in hash table.

(Compatible with UNIX System V)

Usage:

#include <search.h>
ENTRY *hsearch();
loc = hsearch(item,action);

Where:

ENTRY item;: is the hash table entry that is to be found or placed in the hash table.
ACTION action;: is one of ENTER or FIND. These are enumerated values of the type ACTION. If the action is ENTER, "hsearch" will enter the "item" in the table at an appropriate location. If the action is FIND, "hsearch" will find the location of an appropriate item in the table.
ENTRY *loc;: points to the location of an item in the table. If the action was ENTER, this will be where the new item was entered. If the action was FIND, this will be where the old item was found. If an item could not be entered or found, "hsearch" returns the NULL pointer.

Description:

The "hsearch" function is used to make an entry in a hash table. This hash table must have already been created by the "hcreate" function. A program can only have one such hash table at a time.

The ENTRY type is a structure containing the fields "key" and "data". Both of these are pointers to characters. The "key" points to the comparison key of a hash table entry and the "data" points to any other data associated with the entry. The comparison key and the data may have any type, but pointers to them must be cast to (char *) when setting up "item.key" and "item.data". It is up to the programmer to allocate space to hold comparison keys and data for hash table entries. The hash table only contains pointers to this information, not the information itself.

Notes:

"hsearch" normally uses open addressing with a multiplicative hash function. However, the "hsearch" source code has been written to provide other options if the user chooses. This is done by #defining various symbols at the start of the "hsearch" source, then recompiling.

If you #define a symbol DIV, "hsearch" will use remainder modulo table size as its hash function instead of the multiplication function.

If you #define a symbol USCR, "hsearch" will use a user-supplied comparison routine to compare table entries to "item" arguments. This routine should be named "hcompar". Its arguments should be character pointers (one pointing to a table entry and the other to an item). The result should be an integer: zero if the entry and item are the same, positive if the item compares greater than the entry, and negative if the item compares less than the entry.

If you #define a symbol CHAINED, "hsearch" will use a linked list to resolve collisions. When CHAINED is #defined, three other symbols are also important.

START: tells "hsearch" to place new entries at the beginning of the linked list. The default is to place them on the end.
SORTUP: tells "hsearch" to keep the linked list sorted by key in ascending order.
SORTDOWN: tells "hsearch" to keep the linked list sorted by key in descending order.

HSEARCH - enter or find item in hash table.

Usage:

Where:

Description:

Notes:

See Also: