package username.linear;

/**
 * A linear structure that follows the "last in, first out" policy.
 *
 * @author Samuel A. Rebelsky
 * @version 1.1 of March 2006
 */
public interface Stack<T>
  extends LinearStructure<T>
{
  /**
   * Add an element to the stack.  
   *
   * @param val
   *   The object that is to be added.
   * @post
   *   The stack now contains an additional copy of val.
   */
  public void put(T val);

  /**
   * Remove the most-recently-added element that is still in the
   * stack.
   *
   * @return val
   *   An object in the stack.
   * @pre
   *   The stack is not empty.
   * @post
   *   The stack contains one fewer copy of val.
   * @post
   *   Every value in the stack was added less recently than val.
   */
  public T get();

  /**
   * Determine which object will next be returned by get.
   *
   * @return val
   *   An object in the stack
   * @pre
   *   The stack is not empty.
   * @post
   *   Every other value in the stack was added less recently than val.
   */
  public T peek();

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

} // interface Stack<T>