org.apache.commons.collections

## Class ArrayStack

- java.lang.Object
- - java.util.AbstractCollection
  - - java.util.AbstractList
    - - java.util.ArrayList
      - - org.apache.commons.collections.ArrayStack

- All Implemented Interfaces:
    Serializable, Cloneable, Iterable, Collection, List, RandomAccess, Buffer

      public class ArrayStack
      extends ArrayList
      implements Buffer

  An implementation of the `Stack` API that is based on an `ArrayList` instead of a `Vector`, so it is not synchronized to protect against multi-threaded access. The implementation is therefore operates faster in environments where you do not need to worry about multiple thread contention.

  The removal order of an `ArrayStack` is based on insertion order: The most recently added element is removed first. The iteration order is not the same as the removal order. The iterator returns elements from the bottom up, whereas the `remove()` method removes them from the top down.

  Unlike `Stack`, `ArrayStack` accepts null entries.

  Since:
    Commons Collections 1.0
  Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
  Author:
    Craig R. McClanahan, Paul Jack, Stephen Colebourne
  See Also:
    `Stack`, Serialized Form

- - ### Field Summary

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

      `modCount`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ArrayStack()` Constructs a new empty `ArrayStack`.
    `ArrayStack(int initialSize)` Constructs a new empty `ArrayStack` with an initial size.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `empty()` Return `true` if this stack is currently empty.
    `Object` | `get()` Returns the element on the top of the stack.
    `Object` | `peek()` Returns the top item off of this stack without removing it.
    `Object` | `peek(int n)` Returns the n'th item down (zero-relative) from the top of this stack without removing it.
    `Object` | `pop()` Pops the top item off of this stack and return it.
    `Object` | `push(Object item)` Pushes a new item onto the top of this stack.
    `Object` | `remove()` Removes the element on the top of the stack.
    `int` | `search(Object object)` Returns the one-based position of the distance from the top that the specified object exists on this stack, where the top-most element is considered to be at distance `1`.

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

      `add, add, addAll, addAll, clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeRange, retainAll, set, size, subList, toArray, toArray, trimToSize`

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

      `equals, hashCode`

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

      `containsAll, toString`

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

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

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

      `add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray`

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

      `containsAll, equals, hashCode`

- - ### Constructor Detail

    - #### ArrayStack

          public ArrayStack()

      Constructs a new empty `ArrayStack`. The initial size is controlled by `ArrayList` and is currently 10.

    - #### ArrayStack

          public ArrayStack(int initialSize)

      Constructs a new empty `ArrayStack` with an initial size.
      Parameters:
        `initialSize` - the initial size to use
      Throws:
        `IllegalArgumentException` - if the specified initial size is negative

  - ### Method Detail

    - #### empty

          public boolean empty()

      Return `true` if this stack is currently empty.

      This method exists for compatibility with `java.util.Stack`. New users of this class should use `isEmpty` instead.

      Returns:
        true if the stack is currently empty

    - #### peek

          public Object peek()
                      throws EmptyStackException

      Returns the top item off of this stack without removing it.
      Returns:
        the top item on the stack
      Throws:
        `EmptyStackException` - if the stack is empty

    - #### peek

          public Object peek(int n)
                      throws EmptyStackException

      Returns the n'th item down (zero-relative) from the top of this stack without removing it.
      Parameters:
        `n` - the number of items down to go
      Returns:
        the n'th item on the stack, zero relative
      Throws:
        `EmptyStackException` - if there are not enough items on the stack to satisfy this request

    - #### pop

          public Object pop()
                     throws EmptyStackException

      Pops the top item off of this stack and return it.
      Returns:
        the top item on the stack
      Throws:
        `EmptyStackException` - if the stack is empty

    - #### push

          public Object push(Object item)

      Pushes a new item onto the top of this stack. The pushed item is also returned. This is equivalent to calling `add`.
      Parameters:
        `item` - the item to be added
      Returns:
        the item just pushed

    - #### search

          public int search(Object object)

      Returns the one-based position of the distance from the top that the specified object exists on this stack, where the top-most element is considered to be at distance `1`. If the object is not present on the stack, return `-1` instead. The `equals()` method is used to compare to the items in this stack.
      Parameters:
        `object` - the object to be searched for
      Returns:
        the 1-based depth into the stack of the object, or -1 if not found

    - #### get

          public Object get()

      Returns the element on the top of the stack.
      Specified by:
        `get` in interface `Buffer`
      Returns:
        the element on the top of the stack
      Throws:
        `BufferUnderflowException` - if the stack is empty

    - #### remove

          public Object remove()

      Removes the element on the top of the stack.
      Specified by:
        `remove` in interface `Buffer`
      Returns:
        the removed element
      Throws:
        `BufferUnderflowException` - if the stack is empty

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.