## 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:
  Buffer, Cloneable, Collection, List, RandomAccess, Serializable

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: 1.17 $ $Date: 2004/02/18 01:15:42 $
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
`ArrayStack()` Constructs a new empty `ArrayStack`.
`ArrayStack(int initialSize)` Constructs a new empty `ArrayStack` with an initial size.

Method Summary
`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, lastIndexOf, remove, removeRange, set, size, toArray, toArray, trimToSize`

Methods inherited from class java.util.AbstractList
`equals, hashCode, iterator, listIterator, listIterator, subList`

Methods inherited from class java.util.AbstractCollection
`containsAll, remove, removeAll, retainAll, 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, iterator, listIterator, listIterator, remove, removeAll, retainAll, subList`

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-2005 Apache Software Foundation. All Rights Reserved.