package rebelsky.exam3;

/**
 * Linear structures are simple collections that provide (primarily)
 * the put and get methods.
 *
 * @author Samuel A. Rebelsky.
 * @version 1.0 of November 2005
 */
public interface LinearStructure<T>
{
  /**
   * Add an element to the structure.  This mutates
   * the structure.
   *
   * @pre
   *   The structure is not full.
   * @post
   *   The structure contanis exactly one additional copy of
   *   element.
   * @exception Exception
   *   When the structure is full.
   */
  public void put(T element)
    throws Exception;

  /**
   * Grab some element from the structure.  Removes
   * it from the structure.
   *
   * E.g.,
   *   sam.callOn(students.get())
   * @pre
   *   The structure is not empty (and exists).
   * @post
   *   The structure will contain one fewer copy of whatever
   *     was returned.
   * @exception Exception
   *   When the structure is empty
   */
  public T get()
    throws Exception;

  /**
   * Determine if the structure is empty.  Useful to check
   * the precondition of get.
   */
  public boolean isEmpty();

  /**
   * Determine if the structure is full.  Useful to check the
   * precondition of put.
   */
  public boolean isFull();

  /**
   * Determine how many values are currently in the structure.
   */
  public int size();
} // interface LinearStructure