import java.util.Iterator;

import structure.*;

/*
 * Created on Apr 8, 2004
 * @author kim
 *
 * Interface for binary trees
 */
public interface BinaryTreeInterface {
	public static final BinaryTreeInterface EMPTY = new EmptyBinaryTree();
	
	/**
	 * Get left subtree of current node
	 * 
	 * @post Returns reference to left subtree, or EMPTY
	 * 
	 * @return The left subtree of this node
	 */
	public BinaryTreeInterface left();

	/**
	 * Get right subtree of current node
	 * 
	 * @post Returns reference to right subtree, or EMPTY
	 * 
	 * @return The right subtree of this node
	 */
	public BinaryTreeInterface right();

	/**
	 * Get reference to parent of this node
	 * 
	 * @post Returns reference to parent node, or EMPTY
	 * 
	 * @return Reference to parent of this node
	 */
	public BinaryTreeInterface parent();

	/**
	 * Update the left subtree of this node. Parent of the left subtree is
	 * updated consistently. Existing subtree is detached
	 * 
	 * @post Sets left subtree to newLeft re-parents newLeft if not EMPTY
	 * 
	 * @param newLeft
	 *           The root of the new left subtree
	 */
	public void setLeft(BinaryTreeInterface newLeft);

	/**
	 * Update the right subtree of this node. Parent of the right subtree is
	 * updated consistently. Existing subtree is detached
	 * 
	 * @post Sets left subtree to newRight re-parents newRight if not EMPTY
	 * 
	 * @param newRight
	 *           A reference to the new right subtree of this node
	 */
	public void setRight(BinaryTreeInterface newRight);

	/**
	 * Update the parent of this node
	 * 
	 * @post Re-parents this node to parent reference, or EMPTY
	 * 
	 * @param newParent
	 *           A reference to the new parent of this node
	 */
	public void setParent(BinaryTreeInterface newParent);
	
	/**
	 * Returns the number of descendants of node
	 * 
	 * @post Returns the size of the subtree
	 * 
	 * @return Size of subtree
	 */
	public int size();

	/**
	 * Returns reference to root of tree containing n
	 * 
	 * @post Returns the root of the tree node n
	 * 
	 * @return Root of tree
	 */
	public BinaryTreeInterface root();

	/**
	 * Returns height of node in tree. Height is maximum path length to
	 * descendant
	 * 
	 * @post Returns the height of a node in its tree
	 * 
	 * @return The height of the node in the tree
	 */
	public int height();

	/**
	 * Compute the depth of a node. The depth is the path length from node to
	 * root
	 * 
	 * @post Returns the depth of a node in the tree
	 * 
	 * @return The path length to root of tree
	 */
	public int depth();

	/**
	 * Returns true if tree is empty. @post Returns true iff the tree rooted at
	 * node is empty
	 * 
	 * @return True iff tree is empty
	 */
	public boolean isEmpty();

	/**
	 * Returns true if tree is full. A tree is full if adding a node to tree
	 * would necessarily increase its height
	 * 
	 * @post Returns true iff the tree rooted at node is full
	 * 
	 * @return True iff tree is full
	 */
	public boolean isFull();

	/**
	 * Return whether tree is complete. A complete tree has minimal height and
	 * any holes in tree would appear in last level to right.
	 * 
	 * @post Returns true iff the tree rooted at node is complete
	 * 
	 * @return True iff the subtree is complete
	 */
	public boolean isComplete();

	/**
	 * Return true iff the tree is height balanced. A tree is height balanced
	 * iff at every node the difference in heights of subtrees is no greater
	 * than one
	 * 
	 * @post Returns true iff the tree rooted at node is balanced
	 * 
	 * @return True if tree is height balanced
	 */
	public boolean isBalanced();

	/**
	 * Determine if this node is a left child
	 * 
	 * @post Returns true if this is a left child of parent
	 * 
	 * @return True iff this node is a left child of parent
	 */
	public boolean isLeftChild() ;

	/**
	 * Determine if this node is a right child
	 * 
	 * @post Returns true if this is a right child of parent
	 * 
	 * @return True iff this node is a right child of parent
	 */
	public boolean isRightChild();
	/**
	 * Returns value associated with this node
	 * 
	 * @post Returns value associated with this node
	 * 
	 * @return The node's value
	 */
	public Object value();

	/**
	 * Set's value associated with this node
	 * 
	 * @post Sets the value associated with this node
	 * 
	 * @param value
	 *           The new value of this node
	 */
	public void setValue(Object value);

	/**
	 * Generate an in-order iterator of subtree
	 * 
	 * @post Returns an in-order iterator of the elements
	 * 
	 * @return In-order iterator on subtree rooted at this
	 */
	public Iterator iterator();

	/**
	 * Return an iterator to traverse nodes of subtree in-order
	 * 
	 * @post The elements of the binary tree rooted at node are traversed in
	 * preorder
	 * 
	 * @return AbstractIterator to traverse subtree
	 */
	public AbstractIterator preorderIterator();

	/**
	 * Return an iterator to traverse the elements of subtree in-order
	 * 
	 * @post The elements of the binary tree rooted at node node are traversed
	 * in inorder
	 * 
	 * @return An in-order iterator over descendants of node
	 */
	public AbstractIterator inorderIterator() ;

	/**
	 * Return an iterator to traverse the elements of subtree in post-order
	 * 
	 * @pre None @post The elements of the binary tree rooted at node node are
	 * traversed in postorder
	 * 
	 * @return An iterator that traverses descendants of node in postorder
	 */
	public AbstractIterator postorderIterator();

	/**
	 * Method to return a level-order iterator of subtree
	 * 
	 * @pre None @post The elements of the binary tree rooted at node node are
	 * traversed in levelorder
	 * 
	 * @return An iterator to traverse subtree in level-order
	 */
	public AbstractIterator levelorderIterator();
	
	
	/**
	 * Returns a string representing the tree rooted at this node.
	 * <font color="#FF0000">WARNING</font> this can be a very long string.
	 * 
	 * @return A string representing the tree rooted at this node.
	 */
	public String treeString();


}