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

#ifndef _TABLE_H_
#define _TABLE_H_

/* Table_t is an abstract table in which data can be stored.  The data
 * contained in the table includes a key of type 'long' 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, an not a copy of it.  The actual data must be maintained 
 * outside the table.
 */

typedef void *table_t;

typedef void *iterator_t;

/* Create_table returns a new table.  This table will 
 * be able to hold any number of items.
 */
table_t create_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_item(table_t table, long key, void *item);

/* Removes an item from the table.
 */
void destroy_item(table_t table, long key);

/* Returns the number of elements in the table.
 */
long num_items(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_item(table_t table, long 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_table(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.
 */
iterator_t create_iterator(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_item(iterator_t itr, long *key, void **data);

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

#endif