/*------------------------------------------------------------------*/
/* list.h (Version 2:  Indexed Access)                              */
/*------------------------------------------------------------------*/

#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_get(List_T oList, int iIndex);
/* Return the iIndex'th item of oList.
   It is a checked runtime error for oList to be NULL, for iIndex
   to be negative, or for iIndex to be greater than or equal to 
   oList's length. */

void List_insertNext(List_T oList, void *pvItem, int iIndex);
/* Insert pvItem into oList after the iIndex'th item.
   It is a checked runtime error for oList to be NULL, for iIndex
   to be negative, or for iIndex to be greater than or equal to 
   oList's length. */

void List_insertPrev(List_T oList, void *pvItem, int iIndex);
/* Insert pvItem into oList before the iIndex'th item.
   It is a checked runtime error for oList to be NULL, for iIndex
   to be negative, or for iIndex to be greater than or equal to 
   oList's length. */

void List_remove(List_T oList, int iIndex);
/* Remove the iIndex'th item from oList.
   It is a checked runtime error for oList to be NULL, for iIndex
   to be negative, or for iIndex to be greater than or equal to 
   oList's length. */

#endif