zSingleList, zListIterator, zSLSortedList
============================================================================

	Summary  None-view classes for singly linked lists, stacks and queues.

	Remarks  zSingleList implements a container class with a circular
	         singly-linked list structure.  zListIterator implements an
	         iterator class that operates on a zSingleList-type of list.
	         zSLSortedList is a specialized list where items are inserted
	         in sorted order. A singly-linked list is a collection of
	         objects, each of which contains data and information as to the
	         whereabouts of the next element 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 next pointer in the last
	         element set to NULL. 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 next
	         pointer in the tail element points to the head. We only keep
	         one extra pointer, called the tail to the last element in the
	         list. While this might seem backwards, it's the only easy way
	         to insert new elements at head or the tail without much
	         processing. zSingleList lets you navigate through the list
	         only in one direction: forward. It's actually assumed that you
	         don't need to do anything else. If you need increased
	         functionality, use zDoubleList. Even though zSingleList
	         maintains a focus on the item being processed, you can insert
	         new elements only at the beginning or end of the list (See
	         zSLSortedList for additional features).  You can only remove
	         items at the beginning. The get() and update() functions work
	         on the focused item. Also note that zStack and zQueue have
	         different properties for inserting and removing elements.

	Notes    Also, an important property of zSingleList 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 shouldDelete to True
	         with dynamically allocated objects, when a node is destroyed,
	         the object will remain inaccessible in memory. Note that
	         zSingleList is perfectly capable of storing objects of different
             types.  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 zSLSortedList is an
             abstract class with two virtual functions and you'll have to
             override at least one of them.  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.


	ZSIGNLELIST::ZSINGLELIST
	------------------------------------------------------------------------

		Summary  Construct the singly-linked list.

		Syntax   zSingleList(Boolean shouldDelete = False);

		Remarks  This creates an instance of the container and sets the
		         'purge' flag to 'shouldDelete'.  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 new element's
                 data is stored in 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.


	ZLISTITERATOR::ZLISTITERATOR
	------------------------------------------------------------------------

		Summary  Creates an iterator into a list.

		Syntax   zListIterator(zSingleList &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.


	ZSLSORTEDLIST::ZSLSORTEDLIST
	------------------------------------------------------------------------

		Summary  Constructor for the Sorted List

		Syntax   zSLSortedList(Boolean shouldDelete = False);

		Remarks  This one calls the zSingleList constructor and behaves
		         identically. Refer to the information about zSingleList.


	ZSINGLELIST::~ZSINGLELIST
	------------------------------------------------------------------------

		Summary  Destroys the list.

		Syntax   ~zSingleList();

		Remarks  Disposes of the list and all its nodes. See the information
		         on the 'shouldDelete' argument for the constructor for
		         further details.


	ZSINGLELIST::LINK
	------------------------------------------------------------------------

		Summary  Links a new node into the list.

		Syntax   ushort link(const void *data);

		Remarks  This adds a new node at the beginning of the list and sets
		         the focal point to the new node. Returns 1 on success and
		         0 otherwise. For zSLSortedList, it will insert the new node
		         at the proper position as determied by the compare() member
		         function.

		Return   1 on success and 0 otherwise.


	ZSINGLELIST::APPEND
	------------------------------------------------------------------------

		Summary  Append the 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 and 0 otherwise.


	ZSINGLELIST::UNLINK
	------------------------------------------------------------------------

		Summary  Removes a node from the list.

		Syntax   ushort unlink();

		Remarks  Removes the node at the beginning of the list. This function
		         will optionally call freeData() with the data node member
		         as an argument if the shouldPurge is set to True.


	ZSINGLELIST::NEXT
	-------------------------------------------------------------------------

		Summary  Move the focal point to the next node in the list.

		Syntax   ushort next();

		Remarks  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.


	ZSINGLELIST::BEGIN, ZSINGLELIST::END
	------------------------------------------------------------------------

		Summary  Move the focal point to the beginning or end of list.

		Syntax   ushort begin();
                 ushort end();

		Remarks  Moves the focal point to the beginning of the list. Returns
		         1 if the operation was successful, 0 if the list is empty.
		         The second one moves the focal point to the end of the list.
		         Returns 1 if the operation was successful and 0 if the list
		         is empty.


	ZSINGLELIST::ATEND, ZSINGLELIST::ATSTART
	-------------------------------------------------------------------------

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

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

		Remarks  The first one returns True if the focal point is at the end
		         of the list. The second returns True if the focal point is
		         at the start of the list.


	ZSINGLELIST::FOREACH
	------------------------------------------------------------------------

		Summary  Executes 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 action function is defined as follows:

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

                 The focal point will not be changed by this function.


	ZSINGLELIST::FIRSTTHAT
	------------------------------------------------------------------------

		Summary  Finds the first node matching a criteria.

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

		Remarks  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 test function 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.


	ZSINGLELIST::UPDATE
	-------------------------------------------------------------------------

		Summary  Update the data associated with a node.

		Syntax   ushort update(void *aData);

		Remarks  This will update focal point's data with the aData value.
                 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.

		Return   1 on success and 0 if the list is empty.


	ZSINGLELIST::GET
	------------------------------------------------------------------------

		Summary  Retrieves a pointer to the node's data.

		Syntax   void *get() const;

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


	ZSINGLELIST::SIZE
	------------------------------------------------------------------------

		Summary  Return the number of nodes in the list.

		Syntax   long size() const;

		Remarks  Returns the number of the elements currently linkied in
		         the list.


	ZSINGLELIST::ERROR
	------------------------------------------------------------------------

		Summary  Returns 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.


	ZLISTITERATOR::SYNC
	------------------------------------------------------------------------

		Summary  Synchronize the iterator with the list.

		Syntax   void sync();

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


	ZSLSORTEDLIST::COMPARE
	------------------------------------------------------------------------

		Summary  Compare an item from the list with user data.

		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 zSLSortedList. It provides
		         the comparison routine for the list. It 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.


	ZSLSORTEDLIST::KEYOF
	------------------------------------------------------------------------

		Summary  Retrieves the key associated with a data item.

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

		Remarks  This is a pure virtual function that must be provided by
		         each class derived from zSLSortedList.  It is called for
		         each of 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.


	ZSINGLELIST::OPERATOR++
	------------------------------------------------------------------------

		Summary  Advances the focal point to the next node.

		Syntax   ushort operator++();

		Remarks  An alias for next(). See the documentation for next().


	ZSINGLELIST::OPERATOR+=
	------------------------------------------------------------------------

		Summary  Advances the focal point n nodes forward.

		Syntax   ushort operator+=(ushort nelem);

		Remarks  Advance the focal point forward nelem positions in the
		         list. Returns 1 if the operation was successful and 0 if
		         the the end is reached before nelem is exhausted or if the
		         list is empty.


	ZSINGLELIST::OPERATOR()
	------------------------------------------------------------------------

		Summary  Returns the data pointer associated with a node.

		Syntax   void *operator()() const;

		Remarks  Returns a the focal point's data pointer or 0 if list is
		         empty. This is the same as the get() method.

