import ListCursor;

/**
 * Lists with Cursors
 *
 * @author Herman Hacker
 * @author Hermione Hacker
 * @author Herr Doktor Professor Rebelsky
 * @version 1.0 of April 2000
 */
public interface CursoredList
{
    // +-------------------------------------------------
    // | Extractors |
    // +------------+

    /** 
     * Determine if the list contains a particular cursor. 
     * Pre: The cursor is designed to work with this 
     *      particular kind of list.
     * Post: Returns true if the list contains the cursor
     *       and false otherwise.
     */
    public boolean contains(ListCursor cursor);

    /**
     * Get the length of the list.
     * Pre: None
     * Post: Returns the length of the list.
     */
    public int length();

    /**
     * Get a new cursor for the list.
     * Pre: The list is nonempty.
     * Post: Returns a new cursor for the current list.
     */
    public ListCursor newCursor();

    /**
     * Determine the value associated with a cursor.
     * Pre: The cursor is in the current list.
     * Post: Returns the associated value.
     */
    public Object valueAt(ListCursor cursor);

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

    /**
     * Add a value after a cursor.
     * Pre: The cursor is in the list.
     * Post: The new value directly follows the cursor and
     *       precedes the cursor's old successors (if it had
     *       one).  The remaining values maintain their relative
     *       order.  Cursors do not move.
     */
    public void addAfter(Object newValue, ListCursor cursor);
     
    /**
     * Add a value before a cursor.
     * Pre: The cursor is in the list.
     * Post: The new value directly precedes the cursor and
     *       follows the cursor's old predecessor (if it had
     *       one).  The remaining values maintain their relative
     *       order.  Cursors do not move.
     */
    public void addBefore(Object newValue, ListCursor cursor);
     
    /**
     * Add a value to the end of the list.
     * Pre: None
     * Post: The new value is the last value in the list.
     *       Cursors do not move.  The remaining values
     *       maintain their relative order.
     */
    public void addToEnd(Object newValue);

    /**
     * Add a value to the front of the list.
     * Pre: None
     * Post: The new value is the first value.  Cursors do
     *       not move.  The remaining values maintain their 
     *       relative order.
     */
    public void addToFront(Object newValue);

    /**
     * Delete an element given by a cursor.
     * Pre: The cursor is in the list.
     * Post: The cursor is no longer in the list.  The underlying
     *       element is no longer in the list.
     * Post: All remaining elements retain their relative order.
     */
    public void deleteAt(ListCursor cursor);

    /** 
     * Replace an element at the position given by a cursor.
     * Pre: The cursor is in the list.
     * Post: The specified value replaces the old value at the
     *       position.  In fact, valueAt(cursor) returns newValue.
     */
    public void replaceAt(ListCursor cursor, Object newValue);

    /** 
     * Swap two elements of the list. 
     * Pre: Both cursors are in the list.
     * Post: The underlying elements are swapped.
     * Post: The cursors are still at the same places.
     */
    public void swap(ListCursor alpha, ListCursor beta);

} // interface CursoredList