#include "stack.h"

class Stack<ValueType>

This class models a linear structure called a stack in which values are added and removed only from one end. This discipline gives rise to a last-in/first-out behavior (LIFO) that is the defining feature of stacks. The fundamental stack operations are push (add to top) and pop (remove from top). Both of these operations run in O(1) time.

Stacks do not allow access to elements by index, nor can you iterate through the elements using the range-based for loop.
Constructor
Stack()  O(1) Initializes a new empty stack.
Methods
clear()  O(1) Removes all elements from this stack.
equals(stack)  O(N) Returns true if the two stacks contain the same elements in the same order.
isEmpty()  O(1) Returns true if this stack contains no elements.
peek()  O(1) Returns the element on top of this stack, without removing it.
pop()  O(1) Removes the element on top of this stack and returns it.
push(value)  O(1) Adds value onto this stack.
size()  O(1) Returns the number of values in this stack.
toString()  O(N) Returns a printable string representation of this stack.
Operators
stack1 == stack2  O(N) Returns true if stack1 and stack2 contain the same elements.
stack1 != stack2  O(N) Returns true if stack1 and stack2 are different.
ostream << stack  O(N) Outputs the contents of the stack to the given output stream.
istream >> stack  O(N) Reads the contents of the given input stream into the stack.

Constructor detail

Stack();
Initializes a new empty stack. You may also optionally provide an initializer list of values. The newly created stack will contain those values listed left-to-right in order from bottom of the stack to top of stack.

Usage:

Stack<ValueType> stack;
Stack<ValueType> stack = { bottomValue, middleValue, topValue };

Method detail

void clear();
Removes all elements from this stack.

Usage:

stack.clear();

bool equals(const Stack& stack) const;
Returns true if the two stacks contain the exact same element values in the same order. Identical in behavior to the == operator.

Usage:

if (stack1.equals(stack2)) ...

bool isEmpty() const;
Returns true if this stack contains no elements.

Usage:

if (stack.isEmpty()) ...

const ValueType& peek() const;
Returns the element on top of this stack, without removing it. If the stack is empty, this function signals an error.

Usage:

ValueType top = stack.peek();

ValueType pop();
Removes the element from top of this stack and returns it. If the stack is empty, this function signals an error.

Usage:

ValueType top = stack.pop();

void push(const ValueType& value);
Adds the specified value onto this stack.

Usage:

stack.push(value);

int size() const;
Returns the number of values in this stack.

Usage:

int n = stack.size();

string toString() const;
Returns a printable string representation of this stack. The elements listed from left-to-right from the bottom of the stack to the top, such as "{value1, value2, value3}".

Usage:

string str = stack.toString();

ostream& operator<<(const Stack& stack);
Outputs the contents of stack to the given output stream. The output is in the form {value1, value2, value3} where elements are listed left-to-right from the bottom of the stack to the top.

Usage:

cout << stack << endl;

istream& operator>>(Stack& stack);
Reads the contents of the given input stream into stack. Any previous contents of the stack are replaced. The input is expected to be in the form {value1, value2, value3} where elements are listed left-to-right from the bottom of the stack to the top. If unable to read a proper stack from the stream, the operation results in a stream fail state.

Usage:

if (infile >> stack) ...