import CursoredList;

/**
 * Cursors for lists.
 *
 * @author Herman Hacker
 * @author Hermione Hacker
 * @author Herr Doktor Professor Rebelsky
 * @version 1.0 of April 2000
 */
public interface ListCursor
{
    // +------------+------------------------------------
    // | Extractors |
    // +------------+

    /**
     * Make a copy of the cursor.  The copy is at the same
     * place in the same list.  The two cursors move 
     * independently.
     * Pre: The cursor is in a list.
     * Post: Returns a copy.
     */
    public ListCursor makeCopy();

    /**
     * Determine if the cursor equals another cursor.
     * Pre: None
     * Post: Returns true if the two cursors represent the
     *       same position in the same list.  Returns
     *       false otherwise.
     */
    public boolean equals(ListCursor other);

    /** 
     * Determine if the cursor is still in the list. 
     * Pre: None
     * Post: Returns true if the cursor is in a list and
     *       false otherwise.
     */
    public boolean inList();

    // +-----------+-------------------------------------
    // | Modifiers |
    // +-----------+

    /** 
     * Advance the cursor. 
     * Pre: The cursor is in the list.
     * Post: If the cursor was not at the end of the list, the
     *       cursor is now on the next element.  If the cursor
     *       was at the end of the list, it is no longer in the
     *       list. 
     */
    public void advance();

    /**  
     * Move to the same position as another cursor. 
     * Pre: The destination is somewhere in the same list.
     * Post: This cursor is now at the destination.
     */
    public void moveTo(ListCursor destination);

    /** 
     * Reset to the beginning of the list. 
     * Pre: None
     * Post: If the list is nonempty, the cursor is at the
     *       beginning of the list.  If the list is empty,
     *       the cursor is not  in the list.
     */
    public void reset();

    /** 
     * Move the cursor back one step. 
     * Pre: The cursor is in the list.
     * Post: If the cursor was not at the beginning of the list, 
     *       the cursor is now on the previous element.  If the 
     *       cursor was at the end of the list, it is no longer 
     *       in the list. 
     */
    public void retreat();

} // interface ListCursor