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

hlt.language.util

## Class FiniteStack

- java.lang.Object
- - hlt.language.util.FiniteStack

- All Implemented Interfaces:
    ViewableStack

      public class FiniteStack
      extends java.lang.Object
      implements ViewableStack

  This implements a stack of objects, with a finite capacity. If pushing a new object runs over the capacity, room is made for it by discarding the oldest object in the stack (returning it as the return value of the overflowing `push`). This class is useful as a ``forgetful'' stack which may memorize objects only up to a finite history.
  Version:
    Last modified on Tue Jun 19 17:36:35 2012 by hak
  Author:
    Hassan Aït-Kaci
  Copyright:
    © Hassan Aït-Kaci

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FiniteStack()` Constructs a `FiniteStack` object.
    `FiniteStack(int capacity)` Constructs a `FiniteStack` object of specified capacity.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `capacity()` Returns the current total number of assignable slots.
    `java.lang.Object` | `drop()` Removes and returns the oldest object of this `FiniteStack`; returns `null` if it is empty.
    `void` | `flush()` Erases all entries of this `FiniteStack`.
    `java.lang.Object` | `get(int index)` Returns the object at the specified index where 0 is the index of the oldest element, and `size()-1` that of the latest element.
    `boolean` | `isEmpty()` Returns `true` iff this `FiniteStack` is empty.
    `boolean` | `isFull()` Returns `true` iff this `FiniteStack` is full.
    `java.util.Iterator` | `iterator()` Returns an iterator for this `FiniteStack`.
    `java.lang.Object` | `latest()` Returns the latest object pushed onto this `FiniteStack` without removing it, or `null` if it is empty.
    `int` | `latestIndex()` Returns the index of the latest object in this stack, or `-1` if the stack is empty.
    `java.lang.Object` | `oldest()` Returns the oldest object of this `FiniteStack` without removing it, or `null` if it is empty.
    `int` | `oldestIndex()` Returns the index of the oldest object in this stack, or `-1` if the stack is empty.
    `java.lang.Object` | `peek()` Returns the latest object pushed onto this `FiniteStack` without removing it, or `null` if it is empty.
    `java.lang.Object` | `pop()` Removes and returns the latest object pushed onto this `FiniteStack`; returns `null` if it is empty.
    `java.lang.Object` | `push(java.lang.Object object)` Pushes the specified object onto this `FiniteStack`.
    `void` | `setCapacity(int capacity)` Sets the total number of assignable slots to the specified capacity.
    `void` | `setToSize()` Resizes this `FiniteStack`'s container to the current number of assigned slots.
    `int` | `size()` Returns the current number of assigned slots.
    `java.lang.String` | `toString()` Returns a printable string representation of this `FiniteStack`.

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### FiniteStack

          public FiniteStack()

      Constructs a `FiniteStack` object.

    - #### FiniteStack

          public FiniteStack(int capacity)

      Constructs a `FiniteStack` object of specified capacity.

  - ### Method Detail

    - #### isEmpty

          public final boolean isEmpty()

      Returns `true` iff this `FiniteStack` is empty.
      Specified by:
        `isEmpty` in interface `ViewableStack`

    - #### capacity

          public final int capacity()

      Returns the current total number of assignable slots.

    - #### size

          public final int size()

      Returns the current number of assigned slots.
      Specified by:
        `size` in interface `ViewableStack`

    - #### isFull

          public final boolean isFull()

      Returns `true` iff this `FiniteStack` is full.

    - #### flush

          public final void flush()

      Erases all entries of this `FiniteStack`.

    - #### peek

          public final java.lang.Object peek()

      Returns the latest object pushed onto this `FiniteStack` without removing it, or `null` if it is empty.
      Specified by:
        `peek` in interface `ViewableStack`

    - #### latest

          public final java.lang.Object latest()

      Returns the latest object pushed onto this `FiniteStack` without removing it, or `null` if it is empty.

    - #### oldest

          public final java.lang.Object oldest()

      Returns the oldest object of this `FiniteStack` without removing it, or `null` if it is empty.

    - #### latestIndex

          public final int latestIndex()

      Returns the index of the latest object in this stack, or `-1` if the stack is empty.

    - #### oldestIndex

          public final int oldestIndex()

      Returns the index of the oldest object in this stack, or `-1` if the stack is empty.

    - #### get

          public final java.lang.Object get(int index)

      Returns the object at the specified index where 0 is the index of the oldest element, and `size()-1` that of the latest element.
      Specified by:
        `get` in interface `ViewableStack`

    - #### pop

          public final java.lang.Object pop()

      Removes and returns the latest object pushed onto this `FiniteStack`; returns `null` if it is empty.

    - #### drop

          public final java.lang.Object drop()

      Removes and returns the oldest object of this `FiniteStack`; returns `null` if it is empty.

    - #### push

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

      Pushes the specified object onto this `FiniteStack`. If the capacity is exceeded, removes and returns the oldest object in the stack. Otherwise, returns `null`.

    - #### setCapacity

          public final void setCapacity(int capacity)

      Sets the total number of assignable slots to the specified capacity. If the current number of assigned slots is larger than the specified capacity, slots older than the specified capacity are lost.

    - #### setToSize

          public final void setToSize()

      Resizes this `FiniteStack`'s container to the current number of assigned slots. If the stack is empty or full, then this does nothing.

    - #### iterator

          public final java.util.Iterator iterator()

      Returns an iterator for this `FiniteStack`. The stack elements are visited from newest to oldest.
      Specified by:
        `iterator` in interface `ViewableStack`

    - #### toString

          public java.lang.String toString()

      Returns a printable string representation of this `FiniteStack`. The stack elements are listed from newest to oldest.
      Overrides:
        `toString` in class `java.lang.Object`