/*------------------------------------------------------------------*/
/* list.h (Version 4:  Iterator)                                    */
/*------------------------------------------------------------------*/

#ifndef LIST_INCLUDED
#define LIST_INCLUDED

typedef struct List *List_T;
/* A List_T is a doubly-linked list of items. */

typedef struct ListIter *ListIter_T;
/* A ListIter_T is an iterator over a given List_T. */

List_T List_new();
/* Return a new List_T. */

void List_free(List_T oList);
/* Free oList.
   It is a checked runtime error for oList to be NULL. */

int List_getLength(List_T oList);
/* Return the number of items in oList.
   It is a checked runtime error for oList to be NULL. */

void *List_getFirst(List_T oList);
/* Return the first item of oList.
   It is a checked runtime error for oList to be NULL or empty. */

void *List_getLast(List_T oList);
/* Return the last item of oList.
   It is a checked runtime error for oList to be NULL or empty. */

void List_addFirst(List_T oList, void *pvItem);
/* Add pvItem to the beginning of oList.
   It is a checked runtime error for oList to be NULL. */

void List_addLast(List_T oList, void *pvItem);
/* Add pvItem to the end of oList.
   It is a checked runtime error for oList to be NULL. */

void List_removeFirst(List_T oList);
/* Remove the first item of oList.
   It is a checked runtime error for oList to be NULL or empty. */

void List_removeLast(List_T oList);
/* Remove the last item of oList.
   It is a checked runtime error for oList to be NULL or empty. */

void List_toArray(List_T oList, void **ppvArray);
/* Fill ppvArray with the items of oList.
   It is a checked runtime error for oList or ppvArray to be NULL.
   It is an unchecked runtime error for ppvArray to be too small
   to hold all items of oList.  */

void List_map(List_T oList, 
                  void (*pfApply)(void **ppvItem, void *pvExtra),
                  void *pvExtra);
/* Apply function *pfApply to each item of oList, passing pvExtra
   as an extra argument.  That is, for each item pvItem of oList, 
   call (*pfApply)(&pvItem, pvExtra).
   It is a checked runtime error for oList or pfApply to be NULL. */

ListIter_T ListIter_new(List_T oList);
/* Return a new ListIter_T that can iterate over oList.  The 
   ListIter_T is in an invalid state.
   It is a checked runtime error for oList to be NULL. */

void ListIter_free(ListIter_T oListIter);
/* Free oListIter.
   It is a checked runtime error for oListIter to be NULL. */

void ListIter_selectFirst(ListIter_T oListIter);
/* Set oListIter to select the first item of its List_T.  If there
   is a first item, then set oListIter to be in a valid state. 
   Otherwise set oListIter to be in an invalid state.
   It is a checked runtime error for oListIter to be NULL. */
   
void ListIter_selectLast(ListIter_T oListIter);
/* Set oListIter to select the last item of its List_T.  If there
   is a last item, then set oListIter to be in a valid state. 
   Otherwise set oListIter to be in an invalid state.
   It is a checked runtime error for oListIter to be NULL. */

void ListIter_selectNext(ListIter_T oListIter);
/* Set oListIter to select the next item of its List_T.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

void ListIter_selectPrev(ListIter_T oListIter);
/* Set oListIter to select the previous item of its List_T.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

int ListIter_selectionIsValid(ListIter_T oListIter);
/* Return 1 (TRUE) if and only if oListIter is in a valid state. 
   It is a checked runtime error for oListIter to be NULL. */

void *ListIter_get(ListIter_T oListIter);
/* Return the item which oListIter is selecting.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

void ListIter_insertNext(ListIter_T oListIter, void *pvItem);
/* Insert pvItem into oListIter's List_T after the selected item.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

void ListIter_insertPrev(ListIter_T oListIter, void *pvItem);
/* Insert pvItem into oListIter's List_T before the selected item.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

void ListIter_removeAndSelectNext(ListIter_T oListIter);
/* Remove the selected item from oListIter's List_T, and select
   the next item.  If there is a next item, set oListIter to be in 
   a valid state.  Otherwise set oListIter to be in an invalid 
   state. 
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

void ListIter_removeAndSelectPrev(ListIter_T oListIter);
/* Remove the selected item from oListIter's List_T, and select
   the previous item.  If there is a previous item, set oListIter 
   to be in a valid state.  Otherwise set oListIter to be in an 
   invalid state.
   It is a checked runtime error for oListIter to be NULL or in
   an invalid state. */

#endif