/* Cs132List.java 1.2 (interface)               */
/* by Sharon Tuttle                             */
/* last modified: 3-7-03                        */
/*                now includes exceptions       */

public interface Cs132List 
{
    // Purpose: returns true iff list has no elements
    public boolean isEmpty();

    // Purpose: returns number of elements in the list
    public int size();

    // Purpose: add given data newElement to beginning of list.
    public void addFirst(Object newElement);

    // Purpose: add given data newElement to end of list.
    public void addLast(Object newElement);

    // Purpose: add given data newElement to list at position index (where
    //          0 is the index of the first item in the list, 1 is the
    //          index of the 2nd item in the list, etc.)
    //          Throw a ListIndexOutOfBoundsException if the list
    //          index is not between 0 and the size of the array
    //          (I *could* add a new element to the end --- thus "size"
    //          instead of the usual "size - 1").
    //          BUT note --- those elements "after" this position ARE
    //          shifted "up" a position!
    public void add(int index, Object newElement) throws 
       ListIndexOutOfBoundsException;

    // Purpose: IF list is not empty, return FIRST element in list.
    //          If it IS empty, throw a ListEmptyException
    public Object getFirst() throws ListEmptyException;

    // Purpose: IF the list is not empty, return the LAST element in list.
    //          If it IS empty, throw a ListEmptyException
    public Object getLast() throws ListEmptyException;

    // Purpose: return the element at position index in the list
    //          (where 0 is the index of the first item in the list).
    //          If the list is empty, throw a ListEmptyException.
    //          If the index is not between 0 and (list's size - 1),
    //          throw a ListIndexOutOfBoundsException.
    public Object get(int index) throws ListEmptyException,
        ListIndexOutOfBoundsException;

    // Purpose: This seeks to remove the element at position index
    //          of the list (where 0 is the index of
    //          the first element in the list). It will do so and return
    //          the object removed if the index is indeed a position
    //          in the list. (elements "above" in this list are now
    //          one position "lower")
    //
    //          If the list is empty, however, it will
    //          throw a ListEmptyException, and if the index is not
    //          a position in the list, it will throw a 
    //          ListIndexOutOfBoundsException.
    public Object remove(int index) throws ListIndexOutOfBoundsException,
       ListEmptyException;

    // Purpose: empties the list 
    public void clear();
}