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

hlt.language.util

## Class DoubleStack

- java.lang.Object
- - hlt.language.util.DoubleArrayList
  - - hlt.language.util.DoubleStack

-     public class DoubleStack
      extends DoubleArrayList

  This class implements a stack of `double`s (as opposed to `Double`s). It uses the same API as `java.util.Stack` except that the primitive type `double` is used instead of `Object`.
  Version:
    Last modified on Tue Jun 19 17:36:27 2012 by hak
  Author:
    Hassan Aït-Kaci
  Copyright:
    © Hassan Aït-Kaci

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `empty()` Tests if this stack is empty.
    `double` | `peek()` Looks at the object at the top of this stack without removing it from the stack.
    `double` | `peek(int n)` Peeks at n positions from the top of the stack.
    `double` | `pop()` Removes the double at the top of this stack and returns it.
    `double` | `push(double item)` Pushes an item onto the top of this stack.
    `double` | `replace(int n, double e)` Replaces the element at n positions from the top of the stack with a new one; returns the old element.
    `int` | `search(double d)` Returns the 1-based position wherethe specified double is on this stack.
    `java.lang.String` | `toString()` Returns a string representation of this Stack.

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

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

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

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

- - ### Constructor Detail

    - #### DoubleStack

          public DoubleStack()

      Constructs a new empty DoubleStack.

    - #### DoubleStack

          public DoubleStack(int initialCapacity,
                     int capacityIncrement)

      Constructs an empty stack with the specified initial capacity and capacity increment.
      Parameters:
        `initialCapacity` - the initial capacity of the stack.
        `capacityIncrement` - amount by which the capacity is increased on overflow.
      Throws:
        `java.lang.IllegalArgumentException` - if the specified initial capacity is negative.

    - #### DoubleStack

          public DoubleStack(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 double push(double item)

      Pushes an item onto the top of this stack.
      Parameters:
        `item` - the item to be pushed onto this stack.
      Returns:
        the item argument.

    - #### pop

          public final double pop()

      Removes the double at the top of this stack and returns it.
      Returns:
        the double at the top of this stack.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if this stack is empty.

    - #### peek

          public final double peek()

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

    - #### peek

          public final double 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 double replace(int n,
                       double e)

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

    - #### empty

          public final boolean empty()

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

    - #### search

          public final int search(double d)

      Returns the 1-based position wherethe specified double is on this stack. If the double 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.
      Parameters:
        `d` - the desired double.
      Returns:
        the offset from top where the object is located; -1 if not found.

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this Stack. Note that a stack is written top-first!
      Overrides:
        `toString` in class `DoubleArrayList`
      Returns:
        a string representation of this collection.