/*------------------------------------------------------------------*/
/* list.h (Version 1:  Fundamentals)                                */
/*------------------------------------------------------------------*/

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

#endif