packaged linkedlist;

/**
 * A cursor used to step through elements of the list.
 *
 * @author CSC153 2003S
 * @version 1.1 of April 2003
 */
public interface Cursor
{
  /**
   * Get the value associated with the cursor.
   * Preconditions:
   *   The cursor is at a valid position.  (See delete().)
   */
  public Object getValue();

  /**
   * Advance the cursor to the next value.
   * Preconditions: 
   *   The cursor is not at the end of the list.
   *   The cursor is at a valid position.  (See delete().)
   */
  public void advance();

  /**
   * Move the cursor backwards to the previous value.
   * Preconditions: 
   *   The cursor is not at the beginning of the list.
   *   The cursor is at a valid position.  (See delete().)
   */
  public void retreat();

  /**
   * Delete the value associated with the cursor.
   * Preconditions:
   *   The cursor is at a valid position.  
   * Postconditions:
   *   The value associated with the cursor is no longer in the list.
   *   The list is now one element shorter.
   *   All cursors associated with the list are now at unknown
   *     (invalid) positions.
   * @return
   *   The deleted object.
   */
  public Object delete();

  /**
   * Determine if the cursor is at the end of the list.
   * Preconditions:
   *   The cursor is at a valid position (see delete).
   * @return
   *   True, if the cursor is at the end of the list.
   *   False, otherwise.
   */
  public boolean atEnd();

  /**
   * Determine if the cursor is at the front of the list.
   * Preconditions:
   *   The cursor is at a valid position (see delete).
   * @return
   *   True, if the cursor is at the front of the list.
   *   False, otherwise.
   */
  public boolean atFront();

  /**
   * Move the cursor to the end of the list.
   * Preconditions:
   *   The list is nonempty.
   * Postconditions:
   *   The cursor is now at a valid position.
   *   The cursor is now at the end of the list (so atEnd returns
   *     true).
   */
  public void toEnd();

  /**
   * Move the cursor to the front of the list.
   * Preconditions:
   *   The list is nonempty.
   * Postconditions:
   *   The cursor is now at a valid position.
   *   The cursor is now at the front of the list (so atFront returns
   *     true).
   */
  public void toFront();

} // interface Cursor