/* An instance of an implementing class represents a cursor within a
** binary tree (i.e., an object from a class that implements the
** BinTreeWithCursors interface).
*/

public interface BinTreeCursor<T> {

   // observers
   // ---------

   /* Returns (a reference to) the tree in which this cursor lies.
   */
   BinTreeWithCursors<T> getTree();


   // Positional Predicates
   // ---------------------

   /* Reports whether this cursor is at a "phantom" position
   ** (i.e., a place in the tree at which a new node can be grafted).
   */
   boolean atPhantom();

   /* Reports whether this cursor is at the root of its tree.
   */
   boolean atRoot();

   /* Reports whether this cursor is at the left child of its parent.
   */ 
   boolean atLeftChild();

   /* Reports whether this cursor is at the right child of its parent.
   */ 
   boolean atRightChild();

   /* Reports whether this cursor is at a leaf (i.e., a node having
   ** no children).
   */
   boolean atLeaf();


   // Data Retrieval
   // --------------

   /* Returns the data item in the node at which this cursor is positioned.
   ** pre: !atPhantom()
   */
   T datum();


   // Navigation
   // ----------

   /* Moves this cursor to the root of its tree.
   */
   BinTreeCursor<T> toRoot();

   /* Moves this cursor to the parent of where it was.
   ** pre: !atRoot()
   */
   BinTreeCursor<T> toParent();

   /* Moves this cursor to the left child of where it was.
   ** If there is no left child, the cursor is placed at a phantom left child.
   ** pre: !atPhantom()
   */
   BinTreeCursor<T> toLeftChild();

   /* Moves this cursor to the right child of where it was.
   ** If there is no right child, the cursor is placed at a phantom right child.
   ** pre: !atPhantom()
   */
   BinTreeCursor<T> toRightChild();

   /* Returns a clone of this cursor.
   */
   BinTreeCursor<T> clone();


   // Tree Mutation
   // -------------

   /* Replaces the datum in the node where this cursor is by the
   ** given data item.
   */
   void replaceDatum(T newDatum);

   /* Inserts the given tree at this cursor's position, which must 
   ** be a phantom.
   ** pre: atPhantom()
   */
   void graft(BinTreeWithCursors<T> subtree);

   /* Prunes from the tree the subtree rooted at the node where the
   ** cursor is positioned and returns that subtree.  This cursor's 
   ** position becomes the phantom that replaces the pruned subtree.
   ** pre: !atPhantom()
   */
   BinTreeWithCursors<T> prune();


   // Memory Management
   // -----------------

   /* Makes this cursor no longer usable.
   */
   void dispose();
}