CSCI 1302                    Programming Project 4                   Summer 2008

                       Generic Doubly Linked List Class 

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

In this assignment you will implement and time the performance of a generic
doubly linked list class DoubleList<E> based on a private doubly linked
list of nodes for data storage and an associated iterator class DblIterator<E>.
They will perform some of the same functions as LinkedList<E> and 
listIterator<E>.  Since part of the point of the project is to develop your
own implementations, your code must not make use of any other collection
class such as ArrayList<E>, LinkedList<E> or Vector<E>.

Implement your private backing store as a circular doubly linked list with
no dummy node and a single point of access (instead of two, since the
linking will form a circle).

Set up and run basic test cases ("oracles") in JUnit of the constructors and
methods you implement.

Test your classes and their methods on lists of String and lists of Integer.

You may implement more methods than required.

Time selected methods on a large list of randomly generated Integers.  The
methods timed should include remove( element ) when the given element is not
in the list, to see how the average time depends on the list size (e.g.,
time for sizes 100,000, 200,000, 300,000, 400,000, and 500,000).  Also  
time remove( element ) when the given element is in a random position
in the list, again seeing how the average time depends on the list size.

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

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

  public DoubleList(DoubleList<? extends E> otherDoubleList) : initializes a 
          newly created DoubleList object so that it represents the same list
          as otherDoubleList.

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

  public E getFirst( ) : returns the first element in this list.

  public E getLast( ) : returns the last element in this list.

  public  void addFirst(E element) : inserts the given element at the beginning
          of this list.

  public void addLast(E element) : appends the given element to the end of
          this list.

  public boolean remove(Object o) : removes the first occurrence of the
          specified element in this list.  Returns true if the object is
          found and false if not.  A null reference should be treated as 
          something to be removed from the list. 

  public E removeFirst( ) : removes and returns the first element from this
           list.

  public E removeLast( ) : removes and returns the last element from this
           list.

  public DoubleList myConcat(DoubleList otherDoubleList) : returns this 
	  DoubleList object if otherDoubleList is an empty list, and otherwize
	  returns a new DoubleList which represents the concatenation of this
	  list with the other list following it.

  public String toString( ) : produces the String 
	  "DoubleList::elements:\n"+s_0+"\n"+...+"\n"+s_k+"\n"
	  where k+1 is the size of the list, s_0 is the string returned by the 
	  toString method on the first element, and so on through the list
          except that s_j = "nullelement" if s_{j+1} = null.

  public int size( ) : returns the size (number of elements, or length)
	  of this list.
  
  public void clear( ) : removes all of the elements from this list.

  public DbleIterator<E> dblIterator( ) : returns a list-iterator of the
	 elements in this list, starting at the beginning.

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

  public boolean hasNext( ) : returns true if the iteration has more elements
	 in the forward direction.

  public boolean hasPrev( ) : returns true if the iteration has more elements
	 in the bacward direction.

  public E next( ) : returns the next element in the iteration.

  public E prev( ) : returns the previous element in the iteration.

  public void remove( ) : removes from the underlying collection the last
	 element returned by next( ) or prev( ).
				  

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 DoubleList<E>
   methods without editing your code.

  *Your methods should throw IllegalArgumentException, NullPointerException
   or NoSuchElementException as appropriate.  In this regard, note that a
   null reference is considered a valid element of the list and so should
   not generate an exception when it is of the element type E.   
   Also, equals( ) should simply return false if the input is null.  To see
   how to ensure that true is returned only if the input to equals( ) is a
   reference to a DoubleList object, study the Class class in the 1.5.0 API,
   paying special attention to the class literal.

  *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 DoubleList.java, READ.ME, timing_results (giving the results 
   of your timing experiments along with a short analysis of them), and the
   Java code for JUnit tests for all of the required methods (along with any
   extra methods you may have implemented for DoubleList).

  *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):

   20 pts. for good style (meaningful identifier names which indicate
     class/object by capitlaization, consistent indentation and 
     formatting, comments which make intention clear);

   20 pts. for design modularity (generating the goal and playing one
     move should be separate methods; include testing and debugging
     methods);

   10 pts. for working JUnit test code.

   50 pts. for correct operation.

  *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.