zDoubleList, zListCursor, zDLSortedList
============================================================================

	Summary  Generic circular doubly-linked list class with iterators.

	Remarks  zDoubleList implements a container class with a circular
	         doubly-linked list structure.  zListCursor implements an
	         iterator class that operates on a zDoubleList-type of list.
	         zDLSortedList is a specialized list where items are inserted
	         in sorted order.

	Notes    A doubly-linked list is a collection of objects, each of which
	         contains data and information as to the whereabouts of the
	         previous and next elements in the list.  In this form, a list
	         needs to maintain two pointers, one to the beginning and one to
	         the end of the list, with the previous pointer in the head
	         element set to NULL and the next pointer in the last element
	         set to NULL too.  However, it is often more convenient to keep
	         only one pointer to gain access to both the head and the tail.
	         This is a property of the circular list in which the previous
	         pointer in the head element points to the tail and the next
	         pointer in the tail element points to the head. We only keep
	         one extra pointer, called the root to the first element in the
	         list. The zDoubleList, however, departs from the concept of
	         start and end nodes. Instead, it introduces a new one called
	         the focus (or focal point).  All extraction, addition and
	         deletion operations will act on the node that is currently
	         focused.  We also define an iterator class zListCursor which
	         is used to traverse the list and extract infromation from the
	         nodes.  It is not allowed to perform additions or deletetions
	         as these are functions of the list proper. It will be allowed
	         to update elements, though. Also, an important property of
	         zDoubleList is that it is actually a carrier, not a container.
	         This means that it does not store the data in each and every
	         node but just a pointer to it.  If you dynamically allocate
	         your structures before adding them to the list, make sure you
	         set the 'purge' parameter in the constructor to True or memory
	         leaks will occur when you dispose of the list.  If, however,
	         you use staticly allocated structures, then memory will be
	         allocated only once, for the node and then you need not set
	         'purge' to True (in fact, it would be an error).  You must
	         remember that there's a difference between disposing of the
	         pointer to the data when removing the node from the list and
	         disposing of the data itself.  If you forget to set shouldPurge
	         to True with dynamically allocated objects, when a node is
	         destroyed, the object will remain inaccessible in memory. Note
	         that zDoubleList is perfectly capable of storing object of
	         different type.  It will be up to you, however, to ensure
	         type-safe operation since the list does not know anything about
	         the objects it is handed.  It just holds on to them until it is
	         asked to give them up. Also note that zDLSortedList is an
	         abstract class with two virtual functions that you have to
	         override.  You cannot instantiate objects of this type, you
	         have to derive your own class.  Also note that if you use
	         prepend() and append() instead of link(), the sorted property
	         will be compromised.


	ZDOUBLELIST::ZDOUBLELIST
	------------------------------------------------------------------------

		Summary  Creates the container instance and sets internal flags.

		Symmary  zDoubleList(Boolean shouldPurge = False);

		Remarks  This creates an instance of the container and sets the
		         'purge' flag to 'shouldPurge'.  You must set this flag
		         to True if your objects have been dynamically allocated
		         before the insertion. This will cause the freeData()
		         function to be called on each node data when the node
		         is removed from the list.  This is useful if your data
		         elements are pointers.  You can also override freeData()
                 for a derived class, so you can handle pointers to pointers
                 too. This is highly specialized and rarely needed.  The
                 default freeData() will call the delete operator for the
                 data element. Since objects are not stored in the list
                 container, each time you add a new node, a pointer to the
                 the new element's data is copied to the node.  Thus, it is
                 sufficient to delete the node only when the data is not
                 actually a pointer (or pointers) to other things that would
                 need to be disposed of too.


	ZLISTCURSOR::ZLISTCURSOR
	------------------------------------------------------------------------

		Summary  Creates an instance of a list iterator object.

		Syntax   zListCursor(zDoubleList &aList, Boolean atStart);

		Remarks  This will create an instance of the list iterator object.
		         It will be bound to the aList list.  By default, the focal
		         point for the iterator will be set to the beginning of the
		         list.  You can prevent this by setting atStart to False, in
		         which case the focal point of the list will become the focal
		         point for the iterator.


	ZDLSORTEDLIST::ZDLSORTEDLIST
	------------------------------------------------------------------------

		Summary  Creates an instance of a sorted list object.

		Syntax   zDLSortedList(Boolean shouldPurge = False);

		Remarks  Simply calls the zDoubleList() constructor. Note that you
		         cannot actually instantiate zDLSortedList objects (it is
		         an abstract class). You need to derive your own and
		         override the comparison routine.


	ZDOUBLELIST::~ZDOUBLELIST
	------------------------------------------------------------------------

		Summary  Destroys the list and optionally disposes of the nodes.

		Syntax   ~zDoubleList();

		Remarks  Disposes of the list and all its nodes.  See the
		         'shouldPurge' argument for the constructor for details.


	ZDOUBLELIST::LINK, ZDLSORTEDLIST::LINK
	------------------------------------------------------------------------

		Summary	 Links a new node into the list.

		Syntax   ushort link(void *data);

		Remarks  This adds a new node after the focal point and sets the
		         focal point to the new node. For zDLSortedList, it will
		         inster the new node at the proper position as determied
		         by the compare() member function.

		Return   1 on success and 0 otherwise.


	ZDOUBLELIST::APPEND
	------------------------------------------------------------------------

		Summary  Appends a new node to the end of the list.

		Syntax   ushort append(void *data);

		Remarks  This will append the new node to the end of the list.
		         It will set the focal point to the new node.

		Return   1 on succeess, 0 otherwise.


	ZDOUBLELIST::PREPEND
	------------------------------------------------------------------------

		Summary  Adds a new node to the beginning of the list.

		Syntax   ushort prepend(void *data);

		Remarks  This will prepend the new node (add to the beginning of
		         the list). It will set the focal point to the new node.

		Return   1 on success and 0 otherwise.


	ZDOUBLELIST::UNLINK
	------------------------------------------------------------------------

		Summary	 Remove a node from the list.

		Syntax   ushort unlink();

		Remarks  Removes the node at the focal point and sets the focal
		         point to the node following the deleted one.  This function
		         will optionally call freeData() with the data node member
		         as an argument if the shouldPurge is set to True.

		Return   1 on success and 0 otherwise.


	ZDOUBLELIST::NEXT, PREV, BEGIN, END
	ZLISTCURSOR::NEXT, PREV, BEGIN, END
	------------------------------------------------------------------------

		Summary  Change the focal point for the list (or iterator).

		Syntax   ushort next();
                 ushort prev();
                 ushort begin();
                 ushort end();

		Remarks  next() advances the focal point to the next node in the
		         list. Returns 1 if the operation was successful and 0 if
		         the list is empty or if the end is reached. prev() moves
		         the focal point back to the previous node in the list.
		         Returns 1 if the operation was successful and 0 if the
		         list is empty or if the first node has been reached. begin()
                 moves the focal point to the beginning of the list. Returns
                 1 if the operation was successful and 0 if the list is
                 empty. end() moves the focal point to the end of the list.
                 Returns 1 if the operation was successful and 0 if the list
                 is empty.


	ZDOUBLELIST::ATEND, ZDOUBLELIST::ATSTART
	ZLISTVURSOR::ATEND, ZLISTCURSOR::ATSTART
	------------------------------------------------------------------------

		Summary  Test if the focal point is at the beginning or end of list.

		Syntax   Boolean atEnd() const;
                 Boolean atStart() const;

		Remarks  atEnd() Returns True if the focal point is at the end of
		         the list and False otherwise. atStart() returns True if the
		         focal point is at the start of the list and False otherwise.


	ZDOUBLELIST::FOREACH
	------------------------------------------------------------------------

		Summary  Execute a function for each node in the list.

		Syntax   void forEach(ccAppFunc action, void *arg = 0);

		Remarks  Executes the action function for each element in the list.
		         The function will be passed the data of each node as the
		         first argument and the generic arg pointer as the second.
		         The ccAppFunc is defined as follows:

                       typedef void (*ccAppFunc)(void *, void *);

                 The focal point will not be changed by this function.


	ZDOUBLELIST::FIRSTTHAT, ZDOUBLELIST::LASTTHAT
	------------------------------------------------------------------------

		Summary  Finds the first or last nodes matching a test.

		Syntax   ushort firstThat(ccTestFunc test, void *arg = 0);
                 ushort lastThat(ccTestFunc test, void *arg = 0);

		Remarks  firstThat() scans the list from the start for a node for
		         which the test function will return True.  The test
		         function will be passed the data from each node as first
		         argument and the generic pointer 'arg' as the second
		         argument. The ccTestFunc is defined as follows:

                      typedef int (*ccTestFunc)(void *, void *);

                 This function changes the focal point to the found item
                 and returns 1 on success. On failure, it will return 0 and
                 the focal point will be the last node in the list.
                 lastThat() is the same as firstThat() except it starts from
                 the end of the list and proceeds backwards.  In case of
                 failure, the focal point will be set to the beginning of
                 the list.


	ZDOUBLELIST::UPDATE, ZLISTCURSOR::UPDATE
	------------------------------------------------------------------------

		Summary  Updates the data for a particular node.

		Syntax   ushort update(void *aData);

		Remarks  This will update focal point's data with the aData value.
		         Returns 1 on success and 0 if the list is empty. Note that
		         this function will not cause a sorted list to rearrange
		         itself (i.e. if the updated node is out of order, it will
		         remain so). This means that it is required that you unlink
		         the old node and link the new one in. This will ensure that
		         the list stays ordered.


	ZDOUBLELIST::GET, ZLISTCURSOR::GET
	------------------------------------------------------------------------

		Summary  Returns a pointer to the data associated with a node.

		Syntax   void *get() const;

		Remarks  Returns a pointer to the focal point's data or 0 if list
		         is empty.


	ZDOUBLELIST::SIZE
	------------------------------------------------------------------------

		Summary  Return the number of elements in the list.

		Syntax   long size() const;

		Remarks  Returns the number of the elements in the list. This is
		         the number of nodes that are currently linked.


	ZDOUBLELIST::ERROR
	------------------------------------------------------------------------

		Summary  Return the error state of the list.

		Syntax   ushort error();

		Remarks  Returns the error state of the list. This will be either
		         0 or ENOMEM (to indicate memory allocation failure when
		         adding a node). The call to this function will reset the
		         error flag to 0.


	ZLISTCURSOR::SYNC
	------------------------------------------------------------------------

		Summary  Synchronize the list iterator and the list focal point.

		Syntax   void sync();

		Remarks  This function will synchronize the iterator focal point
		         with the list's focal point.


	ZDLSORTEDLIST::COMPARE
	------------------------------------------------------------------------

		Summary  Compares two items in the list to determine sort order.

		Syntax   virtual int compare(void *key1, void *key2) = 0;

		Remarks  This is a pure virtual function which must be provided by
		         each class that is derived from zDLSortedList. It provides
		         the comparison routine for the list. The routine should
		         return a result as follows:

                            < 0 if key1 < key2
                            = 0 if key1 = key2
                            > 0 if key1 > key2

                 This will cause the insertion to be sorted in ascending
                 order.  Of course, you can reverse the values and cause
                 the order to be reverse too. key1 and key2 are generic
                 pointers that have been extracted from the data pointer
                 with the keyOf() member function. You will need to provide
                 the necessary type cast in the function.


	ZDLSORTEDLIST::KEYOF
	------------------------------------------------------------------------

		Summary  Returns the key associated with the node data.

		Syntax   virtual void *keyOf(void *data) = 0;

		Remarks  This is a pure virtual function that must be provided by
		         each class derived from zDLSortedList. It is called for
		         the two arguments to the compare() function. It should
		         return a generic pointer to the key in the data field.
		         This function will be passed a generic pointer to
		         an item in the list. It is your responsibility to ensure
		         that all proper type casts are done and that correct values
		         are returned. Note that the list will call this routine
		         only for the 1st element (the node data), but not for the
		         second one (which is the key). This is presumably because
		         of the possibility of passing a key value and not a whole
		         node as a comparison key.


	ZDOUBLELIST AND ZLISTCURSOR OPERATORS
	------------------------------------------------------------------------

		Summary	 Operators that change the focal point in the list.

		Syntax   ushort operator++();
                 ushort operator--();
                 ushort operator-=(short nelem);
                 ushort operator+=(short nelem);
                 void *operator()() const;

		Remarks  operator++() is an alias for next(). operator--() is an
                 alias for prev(). operator-=() moves the focal point back
                 'nelem' positions. If 'nelem' is negative, the direction is
                 reversed and the focus will be moved forward. This function
                 returns 1 if the operation was successful and 0 if the
                 beginning (or end) are reached before 'nelem' is exhausted
                 or if the list is empty. operator+=() advances the focal
                 point forward 'nelem' positions in the list. If 'nelem' is
                 negative, the direction is reversed and the focus will be
                 moved backwards. Returns 1 if the operation was successful
                 and 0 if the the end (or beginning) are reached before
                 'nelem' is exhausted or if the list is empty. The last
                 operator()() is another alias. This one is for the get()
                 data retrieval function. It returns a pointer to the focal
                 point's data or 0 if list is empty.

