String Sub-Package
The String sub-package provides an API that builds an association between a key string and a value. This association allows users to efficiently retrieve the value from the data store. For example, a client might have a list of names. Associated with each name is a telephone number. The hash table could be used to form a simple directory, in which the name is the key and the telephone number is the value. The client could then find a telephone number by presenting the person's name.
Using the String sub-package involves three steps: creation, insertion, and retrieval. The data store is created by calling either prg_string_hash_table_create() or prg_string_hash_table_create_options(). This determines the number of cells in the hash table as well as the maximum number of characters that will be used by the hashing function. A larger number of characters will help minimize the number of collisions.
After the data store has been created, (key,value) pairs can be inserted using prg_string_hash_table_item_insert() and removed with prg_string_hash_table_item_remove(). A (key,value) pair can be retrieved by calling prg_string_hash_table_item_get(). Lists of all keys or values in the table can be obtained with prg_string_hash_table_keys_get() and prg_string_hash_table_values_get(). You can determine the number of cells in a hash table with prg_string_hash_table_size_get() and the number of items in a hash table with prg_string_hash_table_num_items_get().
When a hash table is no longer needed, destroy it (but not the values contained within it) by using prg_string_hash_table_free(). To destroy both a hash table and its values, use prg_string_hash_table_free_proc().