NAME¶
sdrhash - Simple Data Recorder hash table management functions
SYNOPSIS¶
#include "sdr.h"
Object sdr_hash_create (Sdr sdr, int keyLength,
int estNbrOfEntries,
int meanSearchLength);
int sdr_hash_insert (Sdr sdr, Object hash, char *key,
Address value, Object *entry);
int sdr_hash_delete_entry (Sdr sdr, Object entry);
int sdr_hash_entry_value (Sdr sdr, Object hash, Object entry);
int sdr_hash_retrieve (Sdr sdr, Object hash, char *key,
Address *value, Object *entry);
int sdr_hash_count (Sdr sdr, Object hash);
int sdr_hash_revise (Sdr sdr, Object hash, char *key,
Address value);
int sdr_hash_remove (Sdr sdr, Object hash, char *key,
Address *value);
int sdr_hash_destroy (Sdr sdr, Object hash);
DESCRIPTION¶
The SDR hash functions manage hash table objects in an SDR.
Hash tables associate values with keys. A value is always in the form of an SDR
Address, nominally the address of some stored object identified by the
associated key, but the actual significance of a value may be anything that
fits into a
long. A key is always an array of from 1 to 255 bytes,
which may have any semantics at all.
Keys must be unique; no two distinct entries in an SDR hash table may have the
same key. Any attempt to insert a duplicate entry in an SDR hash table will be
rejected.
All keys must be of the same length, and that length must be declared at the
time the hash table is created. Invoking a hash table function with a key that
is shorter than the declared length will have unpredictable results.
An SDR hash table is an array of linked lists. The location of a given value in
the hash table is automatically determined by computing a "hash" of
the key, dividing the hash by the number of linked lists in the array, using
the remainder as an index to the corresponding linked list, and then
sequentially searching through the list entries until the entry with the
matching key is found.
The number of linked lists in the array is automatically computed at the time
the hash table is created, based on the estimated maximum number of entries
you expect to store in the table and the mean linked list length (i.e., mean
search time) you prefer. Increasing the maximum number of entries in the table
and decreasing the mean linked list length both tend to increase the amount of
SDR heap space occupied by the hash table.
- Object sdr_hash_create(Sdr sdr, int keyLength, int estNbrOfEntries, int
meanSearchLength)
- Creates an SDR hash table. Returns the SDR address of the new hash table
on success, zero on any error.
- int sdr_hash_insert(Sdr sdr, Object hash, char *key, Address value, Object
*entry)
- Inserts an entry into the hash table identified by hash. On
success, places the address of the new hash table entry in entry
and returns zero. Returns -1 on any error.
- int sdr_hash_delete_entry(Sdr sdr, Object entry)
- Deletes the hash table entry identified by entry. Returns zero on
success, -1 on any error.
- Address sdr_hash_entry_value(Sdr sdr, Object hash, Object entry)
- Returns the value of the hash table entry identified by entry.
- int sdr_hash_retrieve(Sdr sdr, Object hash, char *key, Address *value,
Object *entry)
- Searches for the value associated with key in this hash table,
storing it in value if found. If the entry matching key was
found, places the address of the hash table entry in entry and
returns 1. Returns zero if no such entry exists, -1 on any other
failure.
- int sdr_hash_count(Sdr sdr, Object hash)
- Returns the number of entries in the hash table identified by
hash.
- int sdr_hash_revise(Sdr sdr, Object hash, char *key, Address value)
- Searches for the hash table entry matching key in this hash table,
replacing the associated value with value if found. Returns 1 if
the entry matching key was found, zero if no such entry exists, -1
on any other failure.
- int sdr_hash_remove(Sdr sdr, Object hash, char *key, Address *value)
- Searches for the hash table entry matching key in this hash table;
if the entry is found, stores its value in value, deletes the
entry, and returns 1. Returns zero if no such entry exists, -1 on any
other failure.
- void sdr_hash_destroy(Sdr sdr, Object hash);
- Destroys hash, destroying all entries in all linked lists of the
array and destroying the hash table array structure itself. DO NOT use
sdr_free() to destroy a hash table, as this would leave the hash
table's content allocated yet unreferenced.
SEE ALSO¶
sdr(3),
sdrlist(3),
sdrtable(3)