CSCI 1302                    Programming Project 5                   Summer 2008

                          Binary Search Tree Classes

This program is due by midnight on *** Sunday, July 27 ***.

In this assignment you will implement and test two public classes, BasicBST
and a subclass AdaptingBST.  They will each hold a set of integers (values
of primitive data type int) in a binary search tree in which every member 
of the set is the data member of a node with left child and right child
members, but no parent member.  An inorder traversal of a BasicBST or an
AdaptingBST should visit the elements of the set in strictly increasing
order; in particular, there should be no duplicate elements in the set.

Set up and run a suite of test cases ("oracles") in JUnit of the methods
you implement.  The various aspects of your JUnit test suite will count
for 30 points altogether out of 100 in the project assessment.

You may implement more methods than required.

The required methods, with their signatures, return types and behaviors
for BasicBST:

  public BasicBST( ) : initializes a newly created BasicBST object so that
	  it represents an empty set.

  public boolean equals(Object o) : returns true if, and only if, object o is
      a BasicBST object representing the same set as this.

  public  boolean add(int elem) : inserts the indicated element into the 
    set if it is not already a member; returns true if inserted, and false
    if it already belonged to the set.

  public  boolean contains(int elem) : returns true if elem is a member of
    this set, and false if not.

  public String preOrder( String indent ) : returns a string which, when
    printed (by some client), gives the outline of the preorder traversal
    in which an integer at depth d is displayed on its own line, preceeded
    by d copies of the string indent.
    
  public String toString( ) : returns the String 
    "BasicBST::elements:\n"+s_1+"\n"+...+"\n"+s_k+"\n", where s_1, s_2, ...,
    s_k are the members of the set in strictly increasing order.

  public int size( ) : returns the size (number of elements) of this set.
  
  public void clear( ) : removes all of the elements from this set.

For 10 points extra credit implement a real (not lazy) remove( ) in which
the inorder predecessor is always brought up (by copy of data or by relinking
the nodes) to replace the element being removed in the two child case.
The signature for the BasicBST method:

  public boolean remove(int elem) : removes elem from the set if it is a
    member, returning true in that case and false if it was not a member.

AdaptingBST should be a subclass of BasicBST which inherits all of its
methods except for *** the constructor,*** equals( ), add( ), and contains( ).
The latter two should rotate all nodes along the access path, one single
rotation at a time on the way down.  For equals( ) the description is this: 

  public boolean equals(Object o) : returns true if, and only if, object o is
      an AdaptingBST object representing the same set as this.

For the constructor the description is:

  public AdaptingBST( ) : initializes a newly created AdaptingBST object so
      that it represents an empty set.

For 10 points extra credit implement a real (not lazy) remove( ) for
AdaptingBST in which the inorder predecessor is always brought up 
(by copy of data or by relinking the nodes) to replace the element being
removed in the two child case.  As with add( ) and contains( ), remove( )
should perform single rotations along each access path involved in the 
operation, *** except that no rotation is performed along the edge to node
X, say, in case node X is to be removed and does not have two children. ***  


Here are some things to note:

  *The signatures and return types must be followed exactly, so that
   the teaching assistant or the instructor can test your BasicBST
   and AdaptingBST methods without editing your code.

  *The implementations of preOrder( ), toString( ), and clear( )
   should be recursive.  The recursions may be implemented in private
   methods which are called on by the public methods. 

  *The implementations of contains( ), add( ), and (if included) remove( )
   should be iterative.  The iterations may be implemented in private
   methods which are called on by the public methods. 

  *The behavior of equals( ref ) when ref == null is one aspect of the
   contract for equals which you can find under Object in the API.  Your
   implementation should fulfill that contract.  However you should ignore
   the remark about hashCode( ) (the contract for which involves equals( )).

  *Develop this program following proper methodology, starting with a 
   written plan.  Develop the code one method at a time, with readable 
   formatting, meaningful identifier names and illuminating comments.
   For each method, write the test code for it before writing the code for
   the method itself.

  *The submission procedure is described on a separate page which is linked
   from the "projects" page.  Follow it carefully. Your submission should
   include BasicBST.java, AdaptingBST.java, TestBST.java (your JUnit test
   suite) and READ.ME.

  *A project which does not compile on atlas using version 1.5.0 Java will
   score 0.  Projects which do compile properly will be scored as follows
   out of 100 (if on time):

   30 pts. for good style (meaningful identifier names which indicate
     class/object by capitlaization, consistent indentation and 
     formatting, comments which make intention clear), including 15 pts.
     for the JUnit portion;

   20 pts. for design modularity;

   50 pts. for correct operation, including 15 pts. for the JUnit portion.

  *A project which is submitted late will have its score reduced
   by 10 points for every 24 hours or part thereof that it is late.