Stack (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.util

## Class Stack

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList
    - - hlt.language.util.ArrayList
      - - hlt.language.util.Stack

- All Implemented Interfaces:
    ViewableStack, java.lang.Iterable, java.util.Collection, java.util.List
  Direct Known Subclasses:
    Enclosure, ParameterStack

      public class Stack
      extends ArrayList
      implements ViewableStack

  This class implements an unsynchronized `Stack`. It has the exact same API as that of `java.util.Stack` and one may use this in its stead when one does not want to pay the price of mutex synchronization and unneeded range check overhead for every stack operation. In addition, it adds two new constructors that allow to specify the stack's initial capacity.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Stack()` Constructs an empty Stack.
    `Stack(int initialCapacity)` Constructs an empty stack with the specified initial capacity and with its capacity increment equal to zero.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `empty()` Tests if this stack is empty.
    `java.util.Iterator` | `iterator()` Returns an iterator for this `Stack`.
    `java.lang.Object` | `peek()` Looks at the object at the top of this stack without removing it from the stack.
    `java.lang.Object` | `peek(int n)` Peeks at n positions from the top of the stack.
    `java.lang.Object` | `pop()` Removes the object at the top of this stack and returns that object as the value of this function.
    `java.lang.Object` | `push(java.lang.Object item)` Pushes an item onto the top of this stack.
    `java.lang.Object` | `replace(int n, java.lang.Object newObject)` Replaces the object at n positions from the top of the stack with a new one; returns the old object.
    `int` | `search(java.lang.Object o)` Returns the 1-based position where an object is on this stack.

    - ### Methods inherited from class hlt.language.util.ArrayList

      `add, add, addAll, addAll, addAll, addAll, addElement, capacity, clear, clear, clone, contains, containsAll, containsAll, copyInto, elementAt, ensureCapacity, equals, firstElement, get, hasGaps, hashCode, indexOf, indexOf, insertElementAt, isEmpty, lastElement, lastIndexOf, lastIndexOf, remove, remove, removeAll, removeAll, removeAllElements, removeAllFirst, removeAllFirst, removeElement, removeElementAt, removeGaps, removeRange, retainAll, set, setElementAt, setIncrementFactor, setLast, setSize, size, toArray, toString, toStringArray, trimToSize`

    - ### Methods inherited from class java.util.AbstractList

      `addAll, listIterator, listIterator, subList`

    - ### Methods inherited from class java.util.AbstractCollection

      `addAll, containsAll, removeAll, retainAll, toArray`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface hlt.language.util.ViewableStack

      `get, isEmpty, size`

    - ### Methods inherited from interface java.util.Collection

      `addAll, containsAll, removeAll, retainAll, toArray`

    - ### Methods inherited from interface java.util.List

      `addAll, containsAll, removeAll, retainAll, toArray`

- - ### Constructor Detail

    - #### Stack

          public Stack()

      Constructs an empty Stack.

    - #### Stack

          public Stack(int initialCapacity)

      Constructs an empty stack with the specified initial capacity and with its capacity increment equal to zero.

      Parameters:
        `initialCapacity` - the initial capacity of the stack.
      Throws:
        `java.lang.IllegalArgumentException` - if the specified initial capacity is negative.

  - ### Method Detail

    - #### push

          public final java.lang.Object push(java.lang.Object item)

      Pushes an item onto the top of this stack. This has exactly the same effect as: `add(item)`.
      Parameters:
        `item` - the item to be pushed onto this stack.
      Returns:
        the `item` argument.

    - #### pop

          public final java.lang.Object pop()

      Removes the object at the top of this stack and returns that object as the value of this function.
      Returns:
        The object at the top of this stack.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if this stack is empty.

    - #### peek

          public final java.lang.Object peek()

      Looks at the object at the top of this stack without removing it from the stack.
      Specified by:
        `peek` in interface `ViewableStack`
      Returns:
        the object at the top of this stack.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if this stack is empty.

    - #### peek

          public final java.lang.Object peek(int n)

      Peeks at n positions from the top of the stack.
      Parameters:
        `n` - the offset from the top (0 -> top, 1 -> top-1,...)
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index out of range.

    - #### replace

          public final java.lang.Object replace(int n,
                                 java.lang.Object newObject)

      Replaces the object at n positions from the top of the stack with a new one; returns the old object.
      Parameters:
        `n` - the offset from the top (0 -> top, 1 -> top-1,...)
        `newObject` - the new object
      Returns:
        the old object at that position
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index out of range.

    - #### empty

          public final boolean empty()

      Tests if this stack is empty.
      Returns:
        `true` iff this contains no items; `false` otherwise.

    - #### search

          public final int search(java.lang.Object o)

      Returns the 1-based position where an object is on this stack. If the object `o` occurs as an item in this stack, this method returns the distance from the top of the stack of the occurrence nearest the top of the stack; the topmost item on the stack is considered to be at distance `1`. The `equals` method is used to compare `o` to the items in this stack.
      Parameters:
        `o` - the desired object.
      Returns:
        the 1-based position of the object from the top, or -1 if not found.

    - #### iterator

          public java.util.Iterator iterator()

      Returns an iterator for this `Stack`. The stack elements are visited from newest to oldest.
      Specified by:
        `iterator` in interface `ViewableStack`
      Specified by:
        `iterator` in interface `java.lang.Iterable`
      Specified by:
        `iterator` in interface `java.util.Collection`
      Specified by:
        `iterator` in interface `java.util.List`
      Overrides:
        `iterator` in class `ArrayList`