import ListIterator;

/**
 * One version of simple lists.  These objects are dynamic (can grow
 * and shrink), but may limit their size.  Like all lists, they are
 * linear.  They are *not* indexed.
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of November 2000
 */
public interface List
{

  /*
     The default precondition for every method is "the list has
     been initialized".  The default postcondition for every
     extractor is "the list has not been modified".
   */

  // +------------+---------------------------------------------------
  // | Extractors |
  // +------------+

  /**
   * Get an iterator for the list.
   * Produces: An iterator for the current list.
   * Pre: Default
   * Post; Default
   */
  public ListIterator getIterator();

  /**
   * Get the length of the list.
   * Produces: The length of the list.
   * Pre: Default
   * Post: Default
   */
  public int length();

  /**
   * Determine whether or not the list is full.
   * Produces: a boolean value that indicates whether or not the list
   *  is full.
   * Pre: Default.
   * Post: Default.
   * Note: While it may seem that lists should never fill, in some 
   *  implementations they can.  And, after all, all computers have
   *  limited memory.
   */
  public boolean isFull();

  // +-----------------+----------------------------------------------
  // | Adding Elements |
  // +-----------------+

  /**
   * Add an element to the end of the list.
   * Pre: The list is not full.
   * Post: 
   *  (1)The new element is the last element of the list.
   *  (2) The old last element is now the penultimate element.
   *  (3) All remaining elements are in the same order.
   *  (4) Iterators may be disrupted.
   *
   * @exception Exception
   *   if the list is full.
   */
  public void addToEnd(Object element)
    throws Exception;

  /**
   * Add an element to the front of the list.
   * Pre: The list is not full.
   * Post: 
   *  (1)The new element is the first element of the list.
   *  (2) The old first element is now the second element.      
   *  (3) All remaining elements are in the same order.
   *  (4) Iterators may be disrupted.
   *
   * @exception Exception
   *   if the list is full.
   */
  public void addToFront(Object element)
    throws Exception;
 
  // +-------------------+--------------------------------------------
  // | Removing Elements |
  // +-------------------+

  /**
   * Delete all the elements in the list.
   * Pre: Default.
   * Post:
   *   (1) The list contains no elements.
   *   (2) Iterators will be disrupted.
   */
  public void clear();

  /**
   * Delete all copies of an element from the list.
   * Produces: The number of elements deleted.
   * Pre: Default.
   * Post:
   *   (1) The list no longer contains values equal to the element.
   *   (2) The list may be smaller.
   *   (3) All remaining elements are in the same order.
   *   (4) Iterators may be disrupted.
   */
  public int deleteValue(Object element);

  /**
   * Delete the first element from the list.
   * Pre: The list contains at least one element.
   * Post:
   *   (1) The list contains one fewer element.
   *   (2) The list no longer contains its old first element.
   *   (3) The remaining elements are in the same order.
   *   (4) Iterators may be disrupted.
   *
   * @exception Exception
   *   if the list is empty.
   */
  public void deleteFirst()
    throws Exception;

  /**
   * Delete the last element from the list.
   * Pre: The list contains at least one element.
   * Post:
   *   (1) The list contains one fewer element.
   *   (2) The list no longer contains its old last element.
   *   (3) The remaining elements are in the same order.
   *   (4) Iterators may be disrupted.
   *
   * @exception Exception
   *   if the list is empty.
   */
  public void deleteLast()
    throws Exception;


} // interface List