package username.lists;

/**
 * The simplest form of list.  Lists are structures in which each value
 * has a position, each position but the first has a successor, and each
 * value but the last has a predeessor.  Nonempty lists have a unique
 * first element and a unique last element.  In simple lists, the 
 * implementer controls the assignment of values to positions.  Note
 * that if a simple list changes (by addition or deletion), then the
 * positions associated with values may change.
 *
 * @author Samuel A. Rebelsky
 * @author CSC152 2006S
 */
public interface SimpleList<V>
{
  /**
   * Get the position of the front of this list.
   *
   * @return pos
   *   A position that represents the front of the list.
   * @pre
   *   The list should not be empty.
   * @post
   *   The list is not modified.
   *   pos "belongs to" this list.
   */
  public Position front();

  /**
   * Get the position of the end of the list.
   *
   * @return pos
   *   A position that represents the end of the list.
   * @pre
   *   The list should not be empty.
   * @post
   *   The list is not modified.
   *   pos "belongs to" this list.
   */
  public Position rear();

  /**
   * Get the position that follows pos.
   *
   * @return succ
   *   The position of the successor of the value at pos.
   * @pre
   *   pos cannot be the last position in the list.
   *   pos "belongs to" this list.
   * @post
   *   succ "belongs to" this list.
   */
  public Position successor(Position pos);

  /**
   * Get the position that precedes pos.
   *
   * @return pred
   *   The position of the predecessor of the value at pos.
   * @pre
   *   pos cannot be the first position in the list.
   *   pos "belongs to" this list.
   * @post
   *   pred "belongs to" this list.
   */
  public Position predecessor(Position pos);

  /**
   * Get the value at a particular position.
   *
   * @return val
   *   The value at that position in the list.
   * @pre
   *   pos "belongs to" this list.
   * @post
   */
  public V get(Position pos);

  /**
   * Determine if a position represents the first position in
   * the list.
   *
   * @return 
   *   True, if pos is the first position.  False, otherwise.
   * @pre
   * @post
   */
  public boolean isFirst(Position pos);

  /**
   * Determine if a position represents the last position in
   * the list.
   *
   * @return 
   *   True, if pos is the last position.  False, otherwise.
   * @pre
   * @post
   */
  public boolean isLast(Position pos);

  /**
   * Determine if the list is empty.
   *
   * @return
   *   true, if the list is empty; false, otherwise.
   */
  public boolean isEmpty();

  /**
   * Add a value to the list.
   *
   * @pre
   * @post
   *   The list contains an additional copy of value.
   *   All positions associated with this list are now invalid!
   *     (They no longer belong.)
   */
  public void add(V value);

  /**
   * Delete the value at a particular position.
   *
   * @pre
   *   The list is nonempty.
   *   The position "belongs to" the list.
   * @post
   *   The list contains one fewer copy of get(pos).
   *   All positions associated with this list are now invalid!
   *     (They no longer belong.)
   */
  public void delete(Position pos);

  /**
   * Remove all elements from the list.
   *
   * @post
   *   list.isEmpty() returns true.
   *   All positions associated with the list are now invalid!
   */
  public void removeAll();
} // interface SimpleList<V>