/**
 * Lists in which elements maintain their relative positions.
 *
 * @author Samuel A. Rebelsky
 * @version 1.0 of April 2000
 */
public interface SequencedList
{
    
    // +------------------+----------------------------------------
    // | Standard Methods |
    // +------------------+

    /**
     * Convert the list to a string (typically in preparation
     * for printing).
     * Pre: (none)
     * Post: Returns a string of the form
     *       (val1, val2, val3, ..., valn)
     */
    public String toString();

    // +-----------+-----------------------------------------------
    // | Iterators |
    // +-----------+

    /**
     * Get the current element of the list.
     * Pre: There is a current element.
     * Post: Returns the current element.
     * @exception ListException
     *   if there is no current eelment
     */
    public Object getCurrent()
        throws ListException;

    /**
     * Advance the current element to the next element.
     * Pre: The current element is not at the end of the list.
     * Pre: There is a current element.
     * Post: The current element has advanced to the next element.
     * @exception ListException
     *   if the preconditions are not met.
     */
    public void advanceCurrent()
        throws ListException;

    /**
     * Move the current element to the previous element.
     * Pre: The current element is not at the beginning of the list.
     * Pre: There is a current element.
     * Post: The current element is now the previous element.
     * @exception ListException
     *   if the preconditions are not met.
     */
    public void retreatCurrent()
        throws ListException;

    /**
     * Determine if the current element is the first element.
     * Pre: (none)
     * Post: Returns true if the current element is the first element.
     *       Returns false otherwise.
     */
    public boolean atFront();

    /**
     * Determine if the current element is the last element.
     * Pre: (none)
     * Post: Returns true if the current element is the last element.
     *       Returns false otherwise.
     */
    public boolean atEnd();

    /**
     * Reset the current element to the front of the list.
     * Pre: The list is nonempty.
     * Post: The current element is the first element.
     */
    public void toFront();

    /**
     * Reset the current element to the end of the list.
     * Pre: The list is nonempty.
     * Post: The current element is the last element.
     */
    public void toEnd();

    // +-----------+-----------------------------------------------
    // | Accessors |
    // +-----------+

    /**
     * Determine if a list contains a particular element.
     * Pre: The element is not null.
     * Post: Returns true if the list contains that element.
     *       Returns false otherwise.
     */
    public boolean contains(Object element);

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

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

    /**
     * Add an element to the front of the list.
     * Pre: The element is not null.
     * Post: The element is at the front of the list.
     *       The rest of the list is the same.
     */
    public void addToFront(Object element);

    /**
     * Add an element to the end of the list.
     * Pre: The element is not null.
     * Post: The element is at the end of the list.
     *       The rest of the list has not changed.
     */
    public void addToEnd(Object element);

    /**
     * Add an element immediately after the current element.
     * Pre: There is a current element.
     *      The element to be added is not null.
     * Post: The element appears directly after the current element
     *         and before the previous succesor to the current element.
     *       The rest of the list has not changed.
     *       The current element is still the current element.
     */
    public void addAfterCurrent(Object element);

    /**
     * Add an element immediately before the current element.
     * Pre: There is a current element.
     *      The element to be added is not null.
     * Post: The element appears directly before the current element
     *         and after the previous predecessor to the current element.
     *       The rest of the list has not changed.
     *       The current element is still the current element.
     */
    public void addBeforeCurrent(Object element);

    /**
     * Delete the first copy of element from the list.
     * Pre: The element appears in the list.
     * Post: The first copy of the element is deleted.
     *       The length of the list decreases by 1.
     *       The rest of the list maintains its order.
     */
    public void delete(Object element);

    /**
     * Delete the current element of the list.
     * Pre: There is a current element in the list.
     * Post: That element is no longer in the list.
     *       The length of the list decreases by 1.
     *       All other elements maintain their relative order.
     */
    public void deleteCurrent();

} // interface SequencedList