cpsc331.collections

Interface Stack<E>

All Known Implementing Classes:

ListStack

public interface Stack<E>

Provides an interface for an unbounded stack whose elements are of type E.

Stack Invariant: A collection of objects of type E is maintained in last-in first-out order: The object that is visible at the top of the stack is the object that has most recently been pushed onto it, and not yet removed.

Method Summary

Modifier and Type	Method and Description
boolean	isEmpty() Reports whether the stack is currently empty without changing it.
E	peek() Reports the top element of the stack without changing it.
E	pop() Removes an element from the top of the stack and reports it.
void	push(E x) Pushes a new entry onto the stack.

Method Detail

push

void push(E x)

Pushes a new entry onto the stack.

Parameters:

x - the object to be pushed onto the stack

Precondition:

1. The Stack Invariant is satisfied.
2. An element x of type E has been given as input.

Postcondition:

1. The Stack Invariant is satisfied.
2. The input object x has been pushed onto the top of the stack (which is otherwise unchanged).

peek

E peek()

Reports the top element of the stack without changing it.

Returns:

the element at the top of the stack

Throws:

java.util.NoSuchElementException - if the stack is empty

Precondition:

1. The Stack Invariant is satisfied.

Postcondition:

1. The Stack invariant is satisfied.
2. The stack is not changed.
3. If the stack was not empty before this operation then the top element is returned as output.
4. If the stack was empty before this operation then a NoSuchElementException is thrown.

pop

E pop()

Removes an element from the top of the stack and reports it.

Returns:

the element removed from the stack

Throws:

java.util.NoSuchElementException - if the stack is already empty

Precondition:

1. The Stack Invariant is satisfied.

Postcondition:

1. The Stack Invariant is satisfied.
2. If the stack was not empty before this operation then the top element is removed from the stack (which is otherwise unchanged) and this element is returned as output.
3. If the stack was empty before this operation then a NoSuchElementException is thrown and the stack is not changed.

isEmpty

boolean isEmpty()

Reports whether the stack is currently empty without changing it.

Returns:

true if the stack is empty, and false otherwise

Precondition:

1. The Stack Invariant is satisfied.

Postcondition:

1. The Stack Invariant is satisfied.
2. The stack is not changed.
3. If the stack was empty before this operation then “true” is returned as output.
4. If the stack was not empty before this operation then “false” is returned as output.