zBinTree
=============================================================================

    This class provides a simple and efficient binary tree implementation
    with several traversal methods. The info is stored with pointers to
    void, so there is no type-checking.

    Very flexible implementation allows for painless usage without the
    need for excessive derivations. (Yes, not very OOP, I'm afraid!)


    ZBINTREE::ZBINTREE
    -------------------------------------------------------------------------

        Summary   Constructs the binary tree object

        Syntax    zBinTree(fpCompFunc compare, Boolean shouldPurge = False);

        Remarks   This is the only available constructor. It will create
                  an empty tree. The 'compare' argument specifies a pointer
                  to the function used to compare two elements. This routine
                  is defined as follows:

                    int (*fpCompFunc)(const void *item1, const void *item2);

                  The function should return a value <0 if item1 is less
                  than item2; 0 if item1 == item2; >0 if item1 > item2. This
                  routine will be called with pointers to the items as the
                  two parameters.

                  The 'shouldPurge' parameter specifies whether the special
                  cleanup routine should be called when destroying a node
                  in the tree. If this is False, the caller is responsible
                  for freeing the memory used by the elements. If this is
                  True (and a cleanup routine has been specified with a call
                  to the setCleanup() method), the user routine will be
                  invoked with a pointer to the element to destroy as the
                  argument.



    ZBINTREE::~ZBINTREE
    -------------------------------------------------------------------------

        Summary   Destroys the binary tree

        Syntax    virtual ~zBinTree();

        Remarks   The destructor destroys the binary tree object and frees
                  all internally allocated memory. If the user has specified
                  'setPurge' to be True (constructor) and there exists a
                  cleanup routine (see the setCleanup() method), this will
                  also free the memory allocated for the element data itself.


    ZBINTREE::INSERT
    -------------------------------------------------------------------------

        Summary   Inserts a node into the tree

        Syntax    Boolean insert(void *p);

        Remarks   This function inserts a node into the tree. It uses the
                  user-supplied comparison function to determine where to
                  place the new node. Duplicates are not allowed. Note that
                  the class will only store a copy of the pointer it is
                  passed, it will not copy any data.

        Return    True if the insertion was successful
                  False if out of memory or a duplicate found


    ZBINTREE::REMOVE
    -------------------------------------------------------------------------

        Summary   Removes an existing node from the tree

        Syntax    void remove(void *p);
                  void remove();

        Remarks	  There are two versions of the remove() method. The first
                  one will find and remove the element with data 'p'. The
                  second version will remove the element previously located
                  by the find() method. The purging options described in
                  the constructor text apply.

        Return    Nothing


    ZBINTREE::SIZE
    -------------------------------------------------------------------------

        Summary   Return the number of elements in the tree

        Syntax    int size() const;

        Remarks   This function returns the number of elements currently
                  linked in the tree.

        Return    Number of elements


    ZBINTREE::GET
    -------------------------------------------------------------------------

        Summary   Retrieve the data from the current node

        Syntax    void* get();

        Remarks   This function can be used after a call to find() to
                  retrieve the data from a specific node. Note that
                  you must call find() first or this routine will fail. Note
                  that since we are only storing pointers to void, you will
                  need to typecast it to the appropriate type before trying
                  to dereference it.

        Return    On success, returns the data
                  On failure, returns NULL


    ZBINTREE::UPDATE
    -------------------------------------------------------------------------

        Summary   Updates the current node

        Syntax    void update(void *p);

        Remarks   This function updates the current node (located with a call
                  to the find() member routine) with the new data 'p'. If
                  the 'shouldPurge' is True, the old data will be destroyed
                  with a call to the user-supplied cleanup function. You have
                  to call find() before using this method or it will fail.

        Return    Nothing


    ZBINTREE::FIND
    -------------------------------------------------------------------------

        Summary   Locates a specific node

        Syntax    void* find(void *arg);

        Remarks   This method scans the tree to find a node with data equal
                  to 'arg'. It calls the user-supplied comparison function
                  (see the constructor) to do the actual comparisons. Each
                  call starts searching from the root of the tree. There is
                  no provision for resuming a search at a specific location.

        Return    On success, returns non-NULL value
                  On error (not found), returns NULL


    ZBINTREE::FOREACH
    -------------------------------------------------------------------------

        Summary   Tree iterator with an action function

        Syntax    void forEach(fpAppFunc app, void *arg = 0,
                               tree_order order = in);

        Remarks   This iterator will traverse the tree in the specified order
                  and apply the action function 'app' to each node it visits.
                  The action function is defined as:

                    typedef void (*fpAppFunc)(void *item, void *arg);

                  where 'item' is the node data and 'arg' is the parameter
                  'arg' passed to the iterator (defaults to NULL). This
                  additional argument allows you to pass optional data to
                  the action function.

                  All classic traversal modes are available. You can use
                  any of the following enumerated constants as the third
                  parameter to the iterator:

                         enum tree_order { pre, post, in, rev };

                  'pre' specifies pre-order traversal (current, left, right)
                  'post' specifies post-order mode (left, right, current)
                  'in' specifies in-order traversal (left, current, right)
                  'rev' specifies reversed-order mode (right, current, left)

                  Each mode will produce different results. For example,
                  in-order will visit the nodes in ascending order, while
                  reverse-order will visit them in descending order.

        Return    Nothing


    ZBINTREE::OPERATOR()
    -------------------------------------------------------------------------

        Summary   Retrieve the data for the current node

        Syntax    void* operator()();

        Remarks   Same as the get() method.


    ZBINTREE::SETCLEANUP
    -------------------------------------------------------------------------

        Summary   Sets the user-definable cleanup function

        Syntax    void setCleanup(fpCleanupFunc cf);

        Remarks   This routine must be used to specify a function which is
                  to be used when items are destroyed (if and only if the
                  'shouldPurge' parameter in the constructor is True). The
                  cleanup function is defined as follows:

                          typedef void (*fpCleanupFunc)(void*);

                  It will be passed the pointer to the user data and it
                  must dispose of the memory in the proper way. Having a
                  routine like this obviates the need to derive special
                  classes to handle different data.

        Return    Nothing


    ZBINTREE::PURGE
    -------------------------------------------------------------------------

        Summary   Removes all nodes from the tree

        Syntax    void purge();

        Remarks   This method simply removes all nodes from the tree. Note
                  that all specifications regarding the purging of nodes
                  listed above apply. Refer to the setCleanup() method
                  description and the constructor text for more information.

        Return    Nothing

