import java.util.NoSuchElementException;

/**
 * Interface for ordered lists of objects.<br>
 * CSE 373 demonstration program, Winter 2006
 * @author Hal Perkins
 * @version 1/5/06
 */

public interface BasicList {
  
  // queries
  
  /**
   * Return the number of elements in this list
   * @return the number of elements in this list
   */
  public int size();
  
  /**
   * Report whether this list is empty or not
   * @return true if this list contains no elements, otherwise return false
   */
  public boolean isEmpty();
  
  /**
   * Report whether a particular object is contained in this list
   * @param obj the object whose presence in the list is to be tested
   * @return true if obj is an element in this list or false if not
   */
  public boolean contains(Object obj);
  
  /**
   * Return the index of the first occurrence of an object in this list 
   * or -1 if this list does not contain the object.
   * @param obj the object whose location is to be determined
   * @return the location of the object (from 0 to size()-1) if obj
   *         is present, otherwise -1.  If more than one object in the
   *         list is equal to obj (in the sense of equals(...)), return
   *         the position of the first element.
   */
  public int indexOf(Object obj);
  
  // set/get methods
  
  /**
   * Return the object at a given position in this list
   * @param pos position of object to be returned (must be between 0 and size-1())
   * @return the object at the given position
   * @throws IndexOutOfBoundsException if pos < 0 or >= size()-1
   */
  public Object get(int pos)throws IndexOutOfBoundsException;
  
  /**
   * Store an object at a given position in this list
   * @param pos position where the object is to be stored
   *            (must be between 0 and size-1())
   * @param obj the non-null object to be stored
   * @return the object that was previously stored at the given position
   * @throws IndexOutOfBoundsException if pos < 0 or >= size()-1
   */
  public Object set(int pos, Object obj) throws IllegalArgumentException,
                                                IndexOutOfBoundsException;
 
  // basic list manipulation
  
  /**
   * Remove all elements from this list
   */
  public void clear();
  
  /**
   * Add a non-null item to the end of the list
   * @param item object to be added
   * @return true if item successfully added or false if not
   * @throws IllegalArgumentException if item is null
   */
  public boolean add(Object item) throws IllegalArgumentException;
  
  /**
   * Add a non-null item to the beginning of the list
   * @param item object to be added
   * @throws IllegalArgumentException if item is null
   */
  public void addFirst(Object item) throws IllegalArgumentException;
  
  /**
   * Add a non-null item at the specified position in the list
   * @param item object to be added
   * @param pos position where object should be added (must be between 0
   *        and size()-1)
   * @throws IllegalArgumentException if item is null
   * @throws IndexOutOfBoundsException if pos is < 0 or >= size()
   */
  public void add(int pos, Object item) throws IllegalArgumentException,
                                               IndexOutOfBoundsException;
  
  /**
   * Remove the first occurrence of an object from this list
   * @param obj object to be removed; if two or more elements in the
   *            list are equal to obj (in the sense of equals(...),
   *            remove the one with the lowest index.
   * @return true if an element of the list was successfully removed or
   *            false if not
   */
  public boolean remove(Object obj);
  
  /**
   * Remove the element at the specified position from this list
   * @param pos position of object to be removed (must be between 0
   *            and size()-1)
   * @return the element that was previously at the given position
   * @throws IndexOutOfBoundsException if pos is < 0 or >= size()
   */
  public Object remove(int pos) throws IndexOutOfBoundsException;

  /**
   * Remove the element at the beginning of this list
   * @return the element that was previously at the beginning of the list
   * @throws NoSuchElementException if this list is empty
   */
  public Object removeFirst() throws NoSuchElementException;

  /**
   * Remove the element at the end of this list
   * @return the element that was previously at the end of the list
   * @throws NoSuchElementException if this list is empty
   */
  public Object removeLast() throws NoSuchElementException;
  
  // iteration
  
  /**
   * Return an iterator for this list initialized prior to the first element
   * of the list
   * @return a new iterator for this list
   */
  public BasicListIterator iterator();

}