// K_Stack Interface
// Developed and modified by various instructors and TAs for the
// K College Data Structures course, starting with Autumn Spaulding Victor
// and Alyce Brady, circa 2000.
// Modified most recently in October 2025.

import java.util.NoSuchElementException;

/** The K_Stack interface specifies the methods for a <em>Stack</em>
 *  abstract data structure.  Note that the Java Collection Framework does
 *  not include a Stack interface -- instead it has a Stack class that
 *  does not conform to the simple, straight-forward Stack ADT represented
 *  here.  The basic <code>push</code> and <code>pop</code> operations in
 *  this interface act as follows:
 *  <ul>
 *    <li>The push method adds an element to the "top" of the stack.
 *    <li>The pop method acts as follows:
 *        <ul>
 *        <li>If the stack is empty, an exception is thrown.
 *        <li>If the stack contains one element, pop returns that element,
 *          leaving the stack empty.
 *        <li>If the stack contains multiple elements, pop returns the
 *          element at the "top" of the stack, the one that was put there
 *          most recently.  (LIFO - Last In, First Out)
 *        </ul>
 *  </ul>
 **/

public interface K_Stack<T>
{
    /** Returns the number of items currently on the stack.
     **/
    int size();

    /** Returns <code>true</code> if this stack is empty;
     *  <code>false</code> otherwise.
     **/
    boolean isEmpty();

    /** Adds a specified object to the "top" of this stack.
     *    @param item - the object to add to the stack
     **/
    void push(T item);

    /** Removes the element at the "top" of this stack.
     *    @returns the removed element
     *    @throws NoSuchElementException if the stack is empty
     **/
    T pop() throws NoSuchElementException;

    /** Returns the element at the "top" of this stack, without
     *  modifying the stack.
     *    @returns the element at the top of the stack
     *    @throws NoSuchElementException if the stack is empty
     **/
    T peekNext() throws NoSuchElementException;
 
}