import java.util.Iterator;

/**
 * A simplified of the interface java.util.List.
 * This interface contains fewer methods, the 
 * method specifications are simplified and the
 * elements of the list are strings.
 *
 * @author Franck van Breugel
 */
public interface List
{
    /**
     * Appends the specified element to the end of this list.
     *
     * @param element a string.
     * @pre. element != null
     * @return true
     */
    boolean add(String element);
    
    /**
     * Returns the element at the given position in this list.
     *
     * @param index index of the element to return.
     * @pre. index >= 0 && index < size()
     * @return the element at the given position in this list.
     */
    String get(int index);

    /**
     * Replaces the element at the given position in this list with the
     * given element.  Returns the element previously at the specified 
     * position.
     *
     * @param index index of the element to replace.
     * @pre. index >= 0 && index < size()
     * @param element element to be stored at the given position.
     * @pre. element != null
     * @return the element previously at the specified position.
     */
    String set(int index, String element);
    
    /**
     * Returns the number of elements in this list.
     *
     * @return the number of elements in this list.
     */
    int size();
   
    /**
     * Returns a string representation of this list.  The string
     * representation consists of a list of the elements in the
     * order they are returned by its iterator, enclosed in square brackets
     * ("[]").  Adjacent elements are separated by the characters
     * ", " (comma and space).
     *
     * @return a string representation of this collection.
     */
    String toString();
   
    /**
     * Tests if this list contains the given element.
     *
     * @param element a string.
     * @pre. element != null
     * @return true if this list contains the given element,
     * false otherwise.
     */
    boolean contains(String element);
   
    /**
     * Returns the index of the first occurrence of the specified element
     * in this list, or -1 if this list does not contain the element.
     *
     * @param element element to search for.
     * @pre. element != null
     * @return the index of the first occurrence of the specified element in
     * this list, or -1 if this list does not contain the element.
     */
    int indexOf(String element);
   
    /**
     * Inserts the specified element at the specified position in this list.
     *
     * @param index index at which the specified element is to be inserted.
     * @pre. index >= 0 && index <= size()
     * @param element element to be inserted.
     * @pre. element != null
     */
    void add(int index, String element);
   
    /**
     * Removes the element at the specified position in this list.  
     * Returns the element that was removed from this list.
     *
     * @param index the index of the element to be removed.
     * @pre. index >= 0 && index < size()
     * @return the element previously at the specified position.
     */
    String remove(int index);

    /**
     * Compares the specified object with this list for equality.  Returns
     * true if and only if the specified object is also a list, both
     * lists have the same size, and all corresponding pairs of elements in
     * the two lists are equal.
     *
     * @param object the object to be compared for equality with this list.
     * @return true if the specified object is equal to this list, false
     * otherwise.
     */
    boolean equals(Object object);
   
    /**
     * Returns the hash code value for this list.
     *
     * @return the hash code value for this list.
     */
    int hashCode();
   
    /**
     * Returns an iterator over the elements in this list.
     *
     * @return an iterator over the elements in this list.
     */
    Iterator<String> iterator();
}