package rebelsky.generics;

/**
 * Homogenous linear structures.
 *
 * @author Samuel A. Rebelsky
 * @version 0.1 of April 2005
 */
public interface NewLinear<T>
{
  /**
   * Add an element to the structure.  We assume that linear structures
   * never fill, and issue a significant error if the structure fills.
   * (The error is significant and rare enough that we do not list it 
   * as an exception, which means that programmers are not forced to 
   * catch * it.)
   *
   * @param val
   *   The object that is to be added.
   * @post
   *   The collection now contains an additional copy of val.
   */
  public void put(T val);

  /**
   * Remove an element from the structure.  The particular policy
   * for removal is determined by the implementation or variant.
   *
   * @return val
   *   An object in the structure.
   * @pre
   *   The structure is not empty.
   * @post
   *   The structure contains one fewer copy of val.
   */
  public T get();

  /**
   * Determine which object will next be returned by get.
   *
   * @return val
   *   An object in the structure.
   * @pre
   *   The structure is not empty.
   * @post
   *   val is the same value that get() would return.
   *   The structure is unchanged.
   */
  public T peek();

  /**
   * Determine if the structure is empty.
   */
  public boolean isEmpty();

} // interface NewLinear<T>