/*
 *  List Package   --  Craig Kelley 9/16/05 -
 *  CS 385 MWF 10-11a
 *
 *  I reached level "4" in pointer-understanding doing this project!! :)
 *
 *  This is a header package designed to be used in a variety of list
 *  implementations.  The public functions are listed below, as are the
 *  definitions.  Because memory is readily available, each cell has
 *  a pointer to it's next cell and previous cell.
 *
 *  I decided to make this list package very low-level, so that other data
 *  types could be built on top of it easily.  Plus, this offers better
 *  speed because the programmer knows what is actually going on inside
 *  the program and can manipulate the pointers instead of cycling through
 *  the list for every access.  This has the disadvantage of being less
 *  friendly to the programmer, and it has a higher risk in that the
 *  user could pass a faulty pointer-- but if this package is used as-is
 *  this problem should be avoided.
 *
 *  By re-defining L_OBJECT, you may have your list carry any data type.
 *  You can also set L_BADDATA as an object that your list will never
 *  contain so that if you do an invalid retrieval, you can trap it.
 *
 *  note:  the "locate" procedure is left up to the programmer to do, because
 *         it depends on the type of the object, and that is unknown until
 *         compile time.
 */

#include <stdlib.h>

/* Macros */

#define L_OBJECT int
#define L_END (void*)NULL
#define L_POSITION List*
#define L_BADDATA 300

/* The list 'cell' definition */

typedef struct cell {
   L_OBJECT value;		        /* The actual data */
   struct cell* next;			/* a pointer to the next cell */
   struct cell* previous;		/* a pointer to the previous cell */
} List;

/*  Prototypes of object-independant procedures */

List* l_newlist ();
L_POSITION l_first (List* l);
L_POSITION l_last (List* l);
L_OBJECT l_retrieve (L_POSITION p);
int l_insert (List** l, L_POSITION p, L_OBJECT o);
int l_delete (List** l, L_POSITION p);
L_POSITION l_next (L_POSITION p);
L_POSITION l_prev (L_POSITION p);

/*  Function explanations are included in the 'c' file list.p.imp.c */