prg_string_hash_table_create_options()
Abstract
Creates a new hash table (with options).
Syntax
prg_string_hash_table_create_options (table_size, max_chars, options)
| Argument | Type | Description |
|---|---|---|
table_size |
int |
The number of cells the hash table should contain. |
max_chars |
int |
The maximum number of characters in the key string that should be used when computing the hash value. |
options |
int |
Options for creating the hash table (see options). |
Return Type
PrgT_String_Hash_Table *
Pointer to the new hash table.
Header
prg_string_hash_funcs.h
Details
This function creates a new hash table owned by the caller. The number of cells in the table will not change as new (key,value) pairs are added.
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared hash tables must be externally serialized.
The value of table_size relative to the number of (key,value) pairs inserted into the table will help determine the average “lookup speed” of keys. Generally, table_size should be on the order of the maximum number of items expected in the hash table.
- A smaller size means more collisions and thus longer search times for a specified key.
- A larger size means fewer collisions and reduced search time, but increased memory requirements.
For this data structure, only strings can be used as keys. Select a value for max_chars that will most likely capture the unique characters of the anticipated strings. This value can affect the efficiency of hashing:
- A larger value means the hash function computation takes longer.
- A smaller value can mean many strings will hash to the same cell, resulting in a large number of items per cell.
options
options must be one of the following values:
-
PRGC_STRING_HASH_OPT_NONE -
PRGC_STRING_HASH_OPT_STRING_MEM_CLIENT_OWNED—The client takes care of memory management of the strings.This option promotes memory efficiency by not having the hash table duplicate the key strings. When this option is used, the hash table does not copy the strings when
prg_string_hash_table_item_insert()is called. This option is useful to avoid unnecessary memory duplication, especially when the same key string is being used in multiple hash tables. The client must maintain the key strings and is responsible for destroying them. (There is no way to retrieve the actual key strings from a hash table becauseprg_string_hash_table_keys_get()returns copies of the key strings.)If this option is not specified, the hash table will copy the keys and destroy them when items are removed from the tree.
-
PRGC_STRING_HASH_OPT_KEY_CASE_INSENS—The string hash table uses case-insensitive keys.