/*------------------------------------------------------------------*/
/* list.h (Version 3:  Internal Selected Node)                      */
/*------------------------------------------------------------------*/

#ifndef LIST_INCLUDED
#define LIST_INCLUDED

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

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. */

void List_selectFirst(List_T oList);
/* Select the first item of oList.  The selection is valid if and 
   only if there is a first item.
   It is a checked runtime error for oList to be NULL. */
   
void List_selectLast(List_T oList);
/* Select the last item of oList.  The selection is valid if and 
   only if there is a last item.
   It is a checked runtime error for oList to be NULL. */
   
void List_selectNext(List_T oList);
/* Select the next item of oList.  The selection is valid if and 
   only if there is a next item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

void List_selectPrev(List_T oList);
/* Select the previous item of oList.  The selection is valid if and 
   only if there is a previous item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

int List_selectionIsValid(List_T oList);
/* Return 1 (TRUE) if and only if oList's selection is valid.
   It is a checked runtime error for oList to be NULL. */

void *List_get(List_T oList);
/* Return oList's selected item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

void List_insertNext(List_T oList, void *pvItem);
/* Insert pvItem into oList after the selected item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

void List_insertPrev(List_T oList, void *pvItem);
/* Insert pvItem into oList before the selected item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

void List_removeAndSelectNext(List_T oList);
/* Remove the selected item from oList, and select
   the next item.  The selection is valid if and only if there
   is a next item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

void List_removeAndSelectPrev(List_T oList);
/* Remove the selected item from oList, and select
   the previous item.  The selection is valid if and only if there
   is a previous item.
   It is a checked runtime error for oList to be NULL or for its
   selection to be invalid. */

#endif