int strhash_create(strhash *table, unsigned int mod, unsigned int startsize, strhash_hashfunc);
void strhash_destroy(strhash *table);
uint32 strhash_hash(const char *key, unsigned int len);
int strhash_enter (strhash *table, int keyalloc, const char *key, uint32 keylen, int dataalloc, const char *data, uint32 datalen);
void strhash_lookupstart(strhash *table);
int strhash_lookupnext(strhash *table, const char *key, uint32 keylen, char **data, uint32 *datalen);
int strhash_lookup(strhash *table, const char *key, uint32 keylen, char **data, uint32 *datalen);
void strhash_delete(strhash *table);
int strhash_change(strhash *table, int dataalloc, const char *data, uint32 datalen);
void strhash_walkstart(strhash *table);
int strhash_walk(strhash *table, char **key, uint32 *keylen, char **data, uint32 *datalen);
int strhash_load(strhash *table, buffer *b);
int strhash_save(strhash *table, buffer *b);
A strhash is an associative array, mapping keys to values. Keys and values may be strings of up to 2 gigabytes (2^31) bytes of length, containing any possibly character. Keys need not be unique.
strhash_create returns -1 in case of an error.
Note: The strhash library uses the modulus of the hash and the table split factor (in C terms: hash%mod) to select a second level table, and uses the remainder of the hash (hash / mod) modulus the second level size as a index into the second level table.
If keyalloc is set then strhash_enter creates a copy of the key, otherwise strhash_enter creates a reference to the key. key and keylen may be NULL respectively 0 if keyalloc is not set (0).
If dataalloc is set then strhash_enter creates a copy of the value, otherwise strhash_enter creates a reference to the value. data and datalen may be NULL respectively 0 if dataalloc is not set (0).
strhash_enter returns -1 in case of trouble, setting errno appropriately. ENOENT means that either datalen or keylen exceeded 31 bits. ENOMEM means that strhash_enter ran out of memory.
strhash_enter returns 1 if can enter the new key.
After strhash_lookupnext returned 0 no further lookup may be done without first calling strhash_lookupstart.
If data is not a NULL pointer then strhash_lookupnext will put a pointer to the value into *data. If datalen is not a NULL pointer then strhash_lookupnext will put a pointer to the values length into *datalen.
If 1 is returned then pointers to and length of key and value of the record are stored in the appropriate parameter, provided it's not a NULL pointer.
The top level hash table contains mod slots (where mod is an argument given to the strhash_create function). Each slot points to a second level table or to NULL if the second level table is still empty (unused).
Each second level table is allocated as soon as it is needed. It holds a number of pointers to entries. The library grows the second level tables so that they are never more than 50% of the pointers in use. The library doesn't reduce the size of a second level table.
Each entry holds the hash of the key, a pointer to the data, then length of the data, the length of the key and either the key or a pointer to a key.
In short: quite high. On a system where pointers a 32 bits long each record eats 20 bytes for the entry, between 8 and 12 bytes for the second level table, plus the size of the key and the value.
For short keys or data of less then a pointer size length the memory needed is somewhat lower.
Additional memory is used during table splits.
Note: the malloc implementation in the C standard library may waste additional memory.
how to integrate strhash into your projects: strhash-integration(3), the strhash homepage