#ifndef _LIST_H_
#define _LIST_H_

/* A "generic" singly-linked list class.  To get generic types in
   C, we have to use "void *" as the type of the data and then
   cast things back and forth as we insert and remove them from
   the list.  Makes you really appreciate C++ templates, eh? */

struct lnode;

typedef struct lnode *ListCursor;

typedef struct list {
  struct lnode *head, *tail;
} List;


/* Initializes a new list.  Must be called whenever a list is
   created.  Too bad there are no constructors in C. */
void list_initialize(List *);

/* Appends an element to the end of the list. */
void list_append(List *, void *);

/* Puts a new element at the head of the list. */
void list_prepend(List *, void *);

/* Returns true iff the list is empty. */
int list_is_empty(List *);

/* Gets a "Cursor" for the list, which by default starts
   at the head element. */
void list_get_cursor(List *, ListCursor *);

/* Returns true iff the Cursor is at the end of the list. */
int cursor_at_end(ListCursor);

/* Advances the cursor to the next element of the list, and returns
   the data at the new node, assuming that there is a next element.
   If not, it returns NULL. */
void *cursor_advance(ListCursor *);

/* Returns the data at the node currently pointed to by the cursor. */
void *cursor_data(ListCursor);

/* Destroys the list.  Note that this does *not* free any storage
   held by data in the list; it only removes the nodes themselves. */
void list_destroy(List *);

/* Performs an action for every element in the list.  The provided
   function should take a data item as its first element, and 
   the "user data" as its second. */
void list_do(List *list, void (*action)(void *, void *), 
	     void *user_data);

#endif