/*
 * Square Lists Data Structure: 
 *   An implementation based on the description in Dr. Dobb's Journal
 *   May 2003 issue "The SquareList Data Structure"
 *
 * $Id: squarelists.h,v 1.5 2003/09/26 19:31:59 fcs Exp $
 *
 * $Log: squarelists.h,v $
 * Revision 1.5  2003/09/26 19:31:59  fcs
 * Add a #define to squarelists.h can be included multiple times
 * without causing utter catastrophe
 *
 * Revision 1.4  2003/09/15 19:13:35  fcs
 * Update to version 1.1.0
 * SqList_printList takes a FILE pointer so you can control where to print
 * the list.
 *
 * Revision 1.3  2003/05/22 15:21:25  fcs
 * Version 1.0.1
 * 	- prefix all routines with SqList_
 * 	- Add SqList_getNext_r routine
 *
 * Revision 1.2  2003/05/22 00:10:15  fcs
 * Add get* routines
 *
 * Revision 1.1  2003/05/21 20:04:32  fcs
 * Initial revision
 *
 */

#if !defined(_SQUARELISTS_H)

#define _SQUARELISTS_H 1

typedef struct SqList_elem {
	struct SqList_elem *left;	/* top nodes only */
	struct SqList_elem *right;	/* top nodes only */
	struct SqList_elem *up;	/* top and body nodes
				 * top node: up is tail node
				 */
	struct SqList_elem *down;	/* top and body nodes
					 * tail node: this is null
				 	*/
	int vertNodes;		/* top nodes only
				 *	the number of nodes in vertical list
				 */
	int Nodes;		/* head node only
				 *	count of all nodes in structure
				 */
	int maxSize;		/* head node only
				 *	max number of nodes in vertical lists
				 */
	int (*cmp)();
	void *data;		/* the data we are holding... */
} SquareList;

/*
 * SqList_makeHead: allocates the space for the head node, initializes it
 * and returns the pointer to the caller.
 *
 * cmp is the function to be used to compare data nodes in this structure.
 */
SquareList * SqList_makeHead( int (*cmp)() );

/*
 * SqList_insertNode: inserts the passed data element into the structure
 */
int SqList_insertNode(SquareList **head, void *data);

/*
 * SqList_deleteNode: deletes the passed data element from the structure
 */
void * SqList_deleteNode(SquareList **head, void *data);

/*
 * SqList_findNode: searches for the passed data element in the structure
 */
void * SqList_findNode(SquareList **head, void *data);

/*
 * SqList_freeList: free's the entire structure, the freeData routine is called
 * 	to free the underlying data held in the structure
 */
void SqList_freeList(SquareList **head, void (*freeData)());

/*
 * SqList_printList: prints the entire structure
 *
 * head: The head of the structure
 * fp: the FILE * to print to
 * printData: A routine to print the data value
 */
void SqList_printList(SquareList **head, FILE *fp, void (*printData)());

/*
 * SqList_getMin: returns the smallest data element
 *
 * head: the head of the structure
 */
void * SqList_getMin(SquareList **head);

/*
 * SqList_getMax: returns the largest data element
 *
 * head: the head of the structure
 */
void * SqList_getMax(SquareList **head);

/*
 * SqList_getNext: returns the next data element
 *
 * head: the head of the structure
 *
 * returns: pointer to next data element or NULL if
 * 	it has fallen off the end of the SquareList structure.
 *
 * WARNING: THIS IS NOT THREADSAFE IT USES STATIC MEMORY
 *
 * Suggested use is "getMin" followed by getNext until NULL is returned.
 */
void * SqList_getNext(SquareList **head);

/*
 * SqList_getNext_r: returns the next data element
 *
 * head: the head of the structure
 * where: pointer to current node so can remember next node is
 *
 * returns: pointer to next data element or NULL if
 * 	it has fallen off the end of the SquareList structure.
 *
 * Set where to NULL on the first call to start at the minimum value.
 * Do NOT muck with the value of where between calls!
 */
void * SqList_getNext_r(SquareList **head, SquareList **where);

#endif /* !defined(_SQUARELISTS_H) */
