prg_string_hash_table_item_insert()
Abstract
Inserts a new value into a hash table.
Syntax
prg_string_hash_table_item_insert (hash_table_ptr, key_string, contents_ptr, old_contents_pptr)
| Argument | Type | Description |
|---|---|---|
hash_table_ptr |
PrgT_Sting_Hash_Table * |
Pointer to the hash table of interest. |
key_string |
const char * |
Key associated with the value to be inserted into the table. |
contents_ptr |
void * |
Value to be inserted into the table. |
old_contents_pptr |
void ** |
Area to hold a pointer to the previous value for key_string, if any; PRGC_NIL otherwise. |
Return Type
void
No return value.
Header
prg_string_hash_funcs.h
Details
This function uses the key string to determine the location at which to insert contents_ptr. If the hash table already contains a value for this key_string, the previous pointer is placed in old_contents_pptr.
To guard against cases of duplicate keys, your code should check to see if old_contents_pptr is PRGC_NIL. If not, the key was used previously and you must save the previous value somehow. One way is to use the chaining method, in which the hash table entry for duplicate keys is a list of values. To use the chaining method:
- Combine the cell's previous value (from
old_contents_pptr) and the new value (contents_ptr) in a list. - Call
prg_string_hash_table_item_insert()again to store this new list of values at the key position.
Normally, the hash table makes a copy of key_string and the caller is responsible for freeing the original string. If the hash table was created with the PRGC_STRING_HASH_OPT_STRING_MEM_CLIENT_OWNED option, however, the client must maintain the key strings and is responsible for destroying them. See prg_string_hash_table_create_options() for details.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared hash tables must be externally serialized.