/* TreePosition.java */

package tree;

/**
 * An interface for positions (references to nodes) within a Tree class.
 * @author Jonathan Shewchuk
 */

public interface TreePosition {

  public int children();
  /**
   * children() returns the number of children of the node at this position.
   */

  public TreePosition parent() throws NoSuchTreePosition;
  /**
   * parent() constructs a new TreePosition representing the parent of this
   * TreePosition.  Throws an exception if `this' is not a valid position.
   * Returns an invalid TreePosition if this position is at the root.
   */

  public TreePosition child(int c) throws NoSuchTreePosition;
  /**
   * child() constructs a new TreePosition representing the cth child of this
   * TreePosition.  Throws an exception if `this' is not a valid position.
   * Returns an invalid TreePosition if there is no cth child.
   */

  public TreePosition nextSibling() throws NoSuchTreePosition;
  /**
   * nextSibling() constructs a new TreePosition representing the next sibling
   * to the right from this TreePosition.  Throws an exception if `this' is
   * not a valid position.  Returns an invalid TreePosition if there is no
   * sibling to the right of this position.
   */

  public Object elementAt() throws NoSuchTreePosition;
  /**
   * elementAt() returns the item at the current position.
   */

  public void setElementAt(Object value) throws NoSuchTreePosition;
  /**
   * setElementAt() sets the item at the current position.
   */

  public void insertChild(Object item, int c) throws NoSuchTreePosition;
  /**
   * insertChild() inserts an item as the cth child of the current position.
   * Existing children numbered c or higher are shifted one place to the right
   * to accommodate.  If the current position has fewer than c children,
   * the new item is inserted as the last child.  If c < 1, it is treated as
   * if it were 1.
   */

  public void removeLeaf() throws NoSuchTreePosition, BadOperation;
  /**
   * removeLeaf() removes the node at the current position from the tree if
   * it is a leaf.  Throws a BadOperation exception if `this' has one or more
   * children.  Throws a NoSuchTreePosition exception if `this' is not a valid
   * position.  If 'this' has siblings to its right, those siblings are all
   * shifted left by one.
   */

  public boolean isValidPosition();
  /**
   * isValidPosition() determines whether the current position is valid;
   * i.e., whether it refers to an existing node of the tree.
   */

}