/**
 * Collections of values that you can iterate (visit position by
 * position).
 *
 * @author Samuel A. Rebelsky
 * @author CSC153 2004S
 * @version 1.0 of April 2004
 */
public interface GeneralList
{
  // +-----------+---------------------------------------------------------
  // | Observers |
  // +---------=-+

  /**
   * Determine if the list is empty.
   */
  public boolean isEmpty();

  /**
   * Determine the length of the list.
   */
  public int length();

  /**
   * Get the object at a particular position in the list.
   *
   * Pre:
   *   (1) The position is valid.
   *   (2) The position is associated with this list.
   */
  public Object get(Position pos);

  /**
   * Get the first position in the list.
   *
   * Pre:
   *   (1) The list is nonempty.
   */
  public Position first();

  /**
   * Get the last position in the list.
   *
   * Pre:
   *   (1) The list is nonempty.
   */
  public Position last();

  /**
   * Determine if a position is the first position in this list.
   *
   * Pre:
   *   (1) The position is valid.
   *   (2) The position is associated with this list.
   */
  public boolean isFirst(Position pos);

  /**
   * Determine if a position is the last position in this list.
   *
   * Pre:
   *   (1) pos is valid.
   *   (2) pos is associated with this list.
   */
  public boolean isLast(Position pos);

  /**
   * Get the next position in this list.
   *
   * Pre:
   *   (1) pos is valid.
   *   (2) pos is associated with this list.
   *   (3) pos is not the last position in this list.
   */
  public Position next(Position pos);

  /**
   * Get the previous position in this list.
   *
   * Pre:
   *   (1) pos is valid.
   *   (2) pos is associated with this list.
   *   (3) pos is not the first position in this list.
   */
  public Position prev(Position pos);

  /**
   * Determine if a position is a associated with this list.
   */
  public boolean belongs(Position pos);


  // +----------+----------------------------------------------------------
  // | Mutators |
  // +----------+

  /**
   * Add an element to the list.
   *
   * Post: 
   *   (1) The length of the list has increased by 1.
   *   (2) The list now contains another instance of newelt.
   *   (3) All positions previously associated with this list
   *       are now invalid.
   */
  public void add(Object newelt);

  /**
   * Remove all elements from the list.
   *
   * Post: 
   *   (1) The list contains no elements.
   *   (2) All positions previously associated with this list 
   *       are now invalid.
   */
  public void clear();

  /**
   * Remove an element at a specified position from the list.
   *
   * Pre:
   *   (1) The position is valid.
   *   (2) The position is associated with this list.
   *   (3) get(pos) returns obj.
   * Post:
   *   (1) The length of the list has decreased by 1.
   *   (2) The list contains one fewer instance of obj.
   *   (3) All positions previously associated with this list 
   *       are now invalid.
   *   (4) The value returned is obj.
   */
  public Object remove(Position pos);

  /**
   * Replace the element at a specified position in the list.
   *
   * Pre:
   *   (1) The position is valid.
   *   (2) The position is associated with this list.
   *   (3) get(pos) returns oldobj.
   * Post:
   *   (1) get(pos) now returns newobj.
   *   (2) The value returned is oldobj.
   */
  public Object replace(Position pos, Object newobj);

} // interface GeneralList