Purpose

---

  This class provides an array-based implementation of a stack.
  Elements can be added into a stack (a 'push') and retrieved in
  a last in, first out manner (via 'peek' or 'pop' methods).

Category

---

  data types

Methods

---

  push(data): Add data (scalar or vector) to the stack. Return 1 for success.
  peek() : Retrieve, but do not remove the head of the stack
  peek(num): Retrieve, but do not remove, the top num elements on the
            stack.
  pop() : Retrieve and remove the top of the stack
  pop(num): Retrieve and remove the top num elements of the stack
  isEmpty() : Return a 1 if the stack is empty
  toArray() : Return the contents of the stack as an array
  getSize() : Return the number of elements in the array
  contains(num): Return 1 if num is already in the stack somewhere,
                else return 0
  INTERNAL METHODS:
  ensureCapacity(num) : Increase the size of array as necessary to
                        safely insert num more elements.
  fetch(num, /remove) : Driver for peek and pop methods.

Modification History

---

  January 2009: Written by Chris Beaumont
  Oct 2009: Added /NOCOPY keyword to toArray(). cnb.
  April 2010: Added contains() method. cnb