/* 
 * str_table.h
 *
 * Specification of an abstract table data structure.
 *
 */

#ifndef _STR_TABLE_H_
#define _STR_TABLE_H_

/* Str_table_t is an abstract table in which data can be stored.  The data
 * contained in the table includes a key of type 'char*' which is provided
 * when the data is added to the table.  This key is used later to 
 * retrieve the data from the table.  This table only maintains pointers
 * to the data and keys, an not a copy of them.  The actual data and keys
 * must be maintained outside the table.
 */

typedef void *str_table_t;

typedef void *str_iterator_t;

/* Create_table returns a new table.  This table will 
 * be able to hold any number of items.
 */
str_table_t create_str_table();

/* Add_item adds a new data item to the table.  This item is added
 * along with its associated key.  This key will allow the user to 
 * retreive the data pointed to by the void pointer with a get_item call.
 * Returns TRUE if addition was successful, FALSE if key was already in table.
 */
int add_str_table_item(str_table_t table, char* key, void *item);

/* Removes an item from the table.
 */
void destroy_str_table_item(str_table_t table, char* key);

/* Returns the number of elements in the table.
 */
long num_str_table_items(str_table_t table);

/* Get_item returns the pointer to the data associated with the given key.
 * If the key is not recognized, then NULL is returned.
 */
void *get_str_table_item(str_table_t table, char* key);

/* Destroy table deallocates all memory used to store the table.  The memory
 * allocated to store the actual data is not de-allocated, but the 
 * pointers maintained to it in the table are.
 */
void destroy_str_table(str_table_t table);

/* Create_iterator creates an iterator on "table" and returns it.  
 * The iterator is initially at the beginning of the table.  The iterator
 * returns the key/data pairs in the table in some guaranteed order (not
 * necessarily sorted).  If modifications are made to the table during
 * the life of the iterator, its behavior may or may not reflect the
 * modification.  An arbitrary number of iterators may exist on the same
 * table at the same time.
 */
str_iterator_t create_str_table_iterator(str_table_t table);

/* Next_item returns the key/data pair at the present position of "itr",
 * and increments "itr" to the next position.  If the present position of
 * "itr" is past the end of the table, next_item returns FALSE, otherwise
 * TRUE.
 */
int next_str_table_item(str_iterator_t itr, char **key, void **data);

/* Destroy_iterator destroys "itr" and frees all storage associated 
 * with the iterator.
 */
void destroy_str_table_iterator(str_iterator_t itr);

#endif