/*
Name   : LISTS.C
Date   : 19 March, 1990
Author : Kim Moser
System : Microsoft C 5.1 or Turbo C 2.0
Descrip: Generic linked list utilities

General usage:

	Call listnew() to initialize a list.

	Thereafter, call listinsert() or listabsorb() to add elements,
	or listdel() to remove them.

	Call listwipe to remove all elements from a list.

	Call listdispose() to remove all of the list's elements
	AND dispose of the list's internal data structure.
*/

typedef struct list {int i;};
/* This is just a dummy definition used to enforce typing.
   The real list structure is local to the lists.c module. */

extern struct list *listnew(char *fname);
/* Returns a pointer to a newly allocated list */

extern struct list *listopen(char *fname);

extern int listclose(struct list *p);

extern struct list *listwipe(struct list **p, char *fname);
/* If '*p' == NULL then calls listnew(), otherwise disposes of all
   elements in 'p' */

extern int listlen(struct list *p);
/* Returns the length of (i.e. number of elements in) list 'p'.
   Assumes 'p' is an allocated list. */

extern void *listinsert(struct list *p, void *data, int width, int spot);
/* Allocates room for a run of 'width' bytes, copies 'data' into it,
   and adds it to spot 'spot' (offset from 0) in list 'p'.
   If spot >= listlen(p) then adds to end of list.
   Returns pointer to newly allocated data. */

extern void *listabsorb(struct list *p, void *data, int width, int spot);
/* Adds run of 'width' bytes, starting at 'data', to location 'spot'
   (offset from 0) in list 'p'.  If 'spot' >= listlen(p) then
   adds to end of list.  Returns 'data'. */

extern void *listelmt(struct list *p, int spot);
/* Returns a pointer to the spot'th element (offset from 0) in list 'p'.
   If 'p' contains fewer than spot+1 elements then writes warning
   message to warn file and returns NULL. */

extern int elmtwidth(struct list *p, int spot);
/* Returns the width (in bytes) of the spot'th element in list 'p'
   (or 0, if list is uninitialized or if there is no spot'th element). */

extern void listdel(struct list *p, int spot);
/* Deletes spot'th elmt (offset from 0) from list.  If list contains
   fewer than spot+1 elements, then writes warning message and does
   not delete any elements. */

extern void *listdispose(struct list *p);
/* Disposes of list 'p', first freeing memory taken by elements that were
   inserted with listinsert().  (Elements added with listabsorb() are
   not freed; just the references to them are.)  Returns NULL. */