/**
 * Ordered lists with simple cursors.  The cursor indicates the
 * current element of the list.
 *
 * @author Samuel A. Rebelsky
 * @version 1.1 of November 1999
 */
public interface CursoredList {

  /**
   * Add an element to the end of the list.
   */
  public void addToEnd(Object element);

  /**
   * Add an element to the front of the list.
   */
  public void addToFront(Object element);
 
  /**
   * Add an element after the current element.
   * Precondition: There is a current element (specified by the cursor).
   */
  public void addAfterCursor(Object element);
 
  /**
   * Delete the current element.
   * Pre: There is a current element (specified by the cursor).
   * Post: That element is deleted.
   * Post: The cursor advances to the next element, if there is
   *   a next element.  Otherwise, the position of the cursor
   *   is unknown.
   */
  public void delete();

  /**
   * Move the cursor to the next element in the list equal
   * to the specified element.
   * Pre: There is a current element (specified by the cursor).
   * Post: The cursor is on the first equal element that follows
   *   its previous position, if such an element exists.  If no
   *   such element exists, the position of the cursor is unspecified.
   * @exception
   *   If there are no equal elements after the cursor.
   */
  public void find(Object findMe)
    throws Exception;

  /**
   * Move the cursor to the next element in the list equal
   * to the specified element, using compare for comparisons.
   * Pre: There is a current element (specified by the cursor).
   * Post: The cursor is on the first equal element that follows
   *   its previous position, if such an element exists.  If no
   *   such element exists, the position of the cursor is unspecified.
   * @exception
   *   If there are no equal elements after the cursor.
   */
  public void find(Object findMe, Comparator compare)
    throws Exception;

  /**
   * Move the cursor to the front of the list.
   * Pre: The list is nonempty.
   * Post: The cursor is at the front of the list.
   */
  public void front();

  /** 
   * Get the current element of the list.
   * Pre: There is a current element (specified by the cursor).
   */
  public Object getCurrent();

  /**
   * Advance the cursor to the next elmeent.
   * Pre: The current element is not the last element.
   * Pre: There is a current element (specified by the cursor).
   * Post: The cursor advances to the next element, if there is
   *   a next element.  If there is no next element, the
   *   position of the cursor is unknown.
   * @exception Exception
   *   If there is no next element.
   */
  public void advance()
    throws Exception;

} // interface CursoredList