/* Copyright (C) 1998 H. Conrad Cunningham.  All rights reserved.  */

package SoftwareInterfaces;

/**
 * This is the interface to the ranked sequence abstract data type.
 *
 * <p> A ranked sequence is a sequence of elements, each of which has an 
 * associated integer <em>rank</em>.  The rank is the offset of the element 
 * from the beginning of the sequence.  The head (i.e., first) element of 
 * the sequence has rank 0, the next element has rank 1, and so forth.  
 * Each element is a Java object;  primitive data must be wrapped with 
 * instances of the appropriate wrapper classes (e.g., <code>Integer</code>).
 *
 * <p> The ranked sequence abstract data type was inspired, in part, 
 * by Chapter 4 of the book <cite>Data Structures and Algorithms in Java</cite>
 * by Michael T. Goodrich and Roberto Tamassia (Wiley, 1998).
 *
 * @author H. Conrad Cunningham
 * @version 1 June 1998
 */

public interface RankedSequence 
{
    /**
     * Insert a new element at the given rank into the sequence.
     *
     * @param r the rank at which to insert the object
     * @param e the object to be inserted
     * <dt><b>Preconditon:</b> 
     * <dd><code>0 <= r <= length()</code>
     * 
     * @throws AssertionViolation (e.g., if precondition not satisfied)
     * <dt><b>Postcondition:</b> 
     * <dd>object <code>e</code> added as element at rank <code>r</code>.
     *     Ranks of all elements (if any) with old ranks >= <code>r</code>
     *     are increased by one.
     */
    public void insertAtRank(int r, Object e) throws AssertionViolation;


    /**
     * Delete the element at the given rank from the sequence.
     *
     * @param r the rank at which to delete the object
     * <dt><b>Preconditon:</b> 
     * <dd> <code> 0 <= r < length() </code>
     *
     * @throws AssertionViolation (e.g., if precondition not satisfied)
     * <dt><b>Postcondition:</b> 
     * <dd>element at rank <code>r</code> is removed.
     *     Ranks of all elements (if any) with old ranks > <code>r</code>
     *     are decreased by one.
     */
    public void deleteAtRank(int r) throws AssertionViolation;


    /**
     * Replace the element at the given rank in the sequence.
     *
     * @param r the rank at which to replace the object
     * @param e the replacement object
     * <dt><b>Preconditon:</b> 
     * <dd><code>0 <= r < length()</code>
     *
     * @throws AssertionViolation (e.g., if precondition not satisfied)
     * <dt><b>Postcondition:</b> 
     * <dd>element at rank <code>r</code> is replaced by object <code>e</code>.
     */
    public void replaceAtRank(int r, Object e) throws AssertionViolation;


    /**
     * Retrieve the element at the given rank from the sequence.
     *
     * @param r the rank whose value is to be returned
     * <dt><b>Preconditon:</b> 
     * <dd><code>0 <= r < length()</code>
     *
     * @return the element at rank <code>r</code>
     * @throws AssertionViolation (e.g., if precondition not satisfied)
     *     
     */
    public Object elementAtRank(int r) throws AssertionViolation;


    /**
     * Determine the length of (i.e., number of elements in) the sequence.
     *
     * @return the number of elements in the sequence.
     * @throws AssertionViolation
     */
    public int length() throws AssertionViolation;


    /**
     * Determine whether the sequence is empty.
     *
     * @return true if the sequence contains no elements;
     *     otherwise false.
     * @throws AssertionViolation
     */
    public boolean isEmpty() throws AssertionViolation;


    /**
     * Construct an enumeration iterator for the sequence.
     *
     * @return an enumeration iterator for the sequence
     * @throws AssertionViolation
     */
    public java.util.Enumeration elements() throws AssertionViolation;

}