Stack (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.util, class: Stack
Keywords: java.util.Stack class

# Class Stack<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
java.util.Vector<E>
java.util.Stack<E>

Type Parameters:
  `E` - Type of component elements

All Implemented Interfaces:
  `Serializable, Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess, SequencedCollection<E>`

public class Stack<E> extends Vector<E>
The `Stack` class represents a last-in-first-out (LIFO) stack of objects. It extends class `Vector` with five operations that allow a vector to be treated as a stack. The usual `push` and `pop` operations are provided, as well as a method to `peek` at the top item on the stack, a method to test for whether the stack is `empty`, and a method to `search` the stack for an item and discover how far it is from the top.

When a stack is first created, it contains no items.

A more complete and consistent set of LIFO stack operations is provided by the `Deque` interface and its implementations, which should be used in preference to this class. For example:

      Deque<Integer> stack = new ArrayDeque<Integer>();

Since:
  1.0
See Also:
  - Serialized Form

- ## Field Summary

  ### Fields declared in class Vector

  `capacityIncrement, elementCount, elementData`
  Modifier and Type
  Field
  Description
  `protected int`
  `capacityIncrement`
  The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity.
  `protected int`
  `elementCount`
  The number of valid components in this `Vector` object.
  `protected Object[]`
  `elementData`
  The array buffer into which the components of the vector are stored.

  ### Fields declared in class AbstractList

  `modCount`
  Modifier and Type
  Field
  Description
  `protected int`
  `modCount`
  The number of times this list has been structurally modified.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Stack()`
  Creates an empty Stack.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `empty()`
  Tests if this stack is empty.
  `E`
  `peek()`
  Looks at the object at the top of this stack without removing it from the stack.
  `E`
  `pop()`
  Removes the object at the top of this stack and returns that object as the value of this function.
  `E`
  `push(E item)`
  Pushes an item onto the top of this stack.
  `int`
  `search(Object o)`
  Returns the 1-based position where an object is on this stack.

  ### Methods declared in class Vector

  `add, add, addAll, addAll, addElement, capacity, clear, clone, contains, containsAll, copyInto, elementAt, elements, ensureCapacity, equals, firstElement, forEach, get, hashCode, indexOf, indexOf, insertElementAt, isEmpty, iterator, lastElement, lastIndexOf, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeAllElements, removeElement, removeElementAt, removeIf, removeRange, replaceAll, retainAll, set, setElementAt, setSize, size, spliterator, subList, toArray, toArray, toString, trimToSize`
  Modifier and Type
  Method
  Description
  `void`
  `add(int index, E element)`
  Inserts the specified element at the specified position in this Vector.
  `boolean`
  `add(E e)`
  Appends the specified element to the end of this Vector.
  `boolean`
  `addAll(int index, Collection<? extends E> c)`
  Inserts all of the elements in the specified Collection into this Vector at the specified position.
  `boolean`
  `addAll(Collection<? extends E> c)`
  Appends all of the elements in the specified Collection to the end of this Vector, in the order that they are returned by the specified Collection's Iterator.
  `void`
  `addElement(E obj)`
  Adds the specified component to the end of this vector, increasing its size by one.
  `int`
  `capacity()`
  Returns the current capacity of this vector.
  `void`
  `clear()`
  Removes all of the elements from this Vector.
  `Object`
  `clone()`
  Returns a clone of this vector.
  `boolean`
  `contains(Object o)`
  Returns `true` if this vector contains the specified element.
  `boolean`
  `containsAll(Collection<?> c)`
  Returns true if this Vector contains all of the elements in the specified Collection.
  `void`
  `copyInto(Object[] anArray)`
  Copies the components of this vector into the specified array.
  `E`
  `elementAt(int index)`
  Returns the component at the specified index.
  `Enumeration<E>`
  `elements()`
  Returns an enumeration of the components of this vector.
  `void`
  `ensureCapacity(int minCapacity)`
  Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
  `boolean`
  `equals(Object o)`
  Compares the specified Object with this Vector for equality.
  `E`
  `firstElement()`
  Returns the first component (the item at index `0`) of this vector.
  `void`
  `forEach(Consumer<? super E> action)`
  Performs the given action for each element of the `Iterable` until all elements have been processed or the action throws an exception.
  `E`
  `get(int index)`
  Returns the element at the specified position in this Vector.
  `int`
  `hashCode()`
  Returns the hash code value for this Vector.
  `int`
  `indexOf(Object o)`
  Returns the index of the first occurrence of the specified element in this vector, or -1 if this vector does not contain the element.
  `int`
  `indexOf(Object o, int index)`
  Returns the index of the first occurrence of the specified element in this vector, searching forwards from `index`, or returns -1 if the element is not found.
  `void`
  `insertElementAt(E obj, int index)`
  Inserts the specified object as a component in this vector at the specified `index`.
  `boolean`
  `isEmpty()`
  Tests if this vector has no components.
  `Iterator<E>`
  `iterator()`
  Returns an iterator over the elements in this list in proper sequence.
  `E`
  `lastElement()`
  Returns the last component of the vector.
  `int`
  `lastIndexOf(Object o)`
  Returns the index of the last occurrence of the specified element in this vector, or -1 if this vector does not contain the element.
  `int`
  `lastIndexOf(Object o, int index)`
  Returns the index of the last occurrence of the specified element in this vector, searching backwards from `index`, or returns -1 if the element is not found.
  `ListIterator<E>`
  `listIterator()`
  Returns a list iterator over the elements in this list (in proper sequence).
  `ListIterator<E>`
  `listIterator(int index)`
  Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list.
  `E`
  `remove(int index)`
  Removes the element at the specified position in this Vector.
  `boolean`
  `remove(Object o)`
  Removes the first occurrence of the specified element in this Vector If the Vector does not contain the element, it is unchanged.
  `boolean`
  `removeAll(Collection<?> c)`
  Removes from this Vector all of its elements that are contained in the specified Collection.
  `void`
  `removeAllElements()`
  Removes all components from this vector and sets its size to zero.
  `boolean`
  `removeElement(Object obj)`
  Removes the first (lowest-indexed) occurrence of the argument from this vector.
  `void`
  `removeElementAt(int index)`
  Deletes the component at the specified index.
  `boolean`
  `removeIf(Predicate<? super E> filter)`
  Removes all of the elements of this collection that satisfy the given predicate (optional operation).
  `protected void`
  `removeRange(int fromIndex, int toIndex)`
  Removes from this list all of the elements whose index is between `fromIndex`, inclusive, and `toIndex`, exclusive.
  `void`
  `replaceAll(UnaryOperator<E> operator)`
  Replaces each element of this list with the result of applying the operator to that element (optional operation).
  `boolean`
  `retainAll(Collection<?> c)`
  Retains only the elements in this Vector that are contained in the specified Collection.
  `E`
  `set(int index, E element)`
  Replaces the element at the specified position in this Vector with the specified element.
  `void`
  `setElementAt(E obj, int index)`
  Sets the component at the specified `index` of this vector to be the specified object.
  `void`
  `setSize(int newSize)`
  Sets the size of this vector.
  `int`
  `size()`
  Returns the number of components in this vector.
  `Spliterator<E>`
  `spliterator()`
  Creates a late-binding and fail-fast `Spliterator` over the elements in this list.
  `List<E>`
  `subList(int fromIndex, int toIndex)`
  Returns a view of the portion of this List between fromIndex, inclusive, and toIndex, exclusive.
  `Object[]`
  `toArray()`
  Returns an array containing all of the elements in this Vector in the correct order.
  `<T> T[]`
  `toArray(T[] a)`
  Returns an array containing all of the elements in this Vector in the correct order; the runtime type of the returned array is that of the specified array.
  `String`
  `toString()`
  Returns a string representation of this Vector, containing the String representation of each element.
  `void`
  `trimToSize()`
  Trims the capacity of this vector to be the vector's current size.

  ### Methods declared in class Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

  ### Methods declared in interface Collection

  `parallelStream, stream, toArray`
  Modifier and Type
  Method
  Description
  `default Stream<E>`
  `parallelStream()`
  Returns a possibly parallel `Stream` with this collection as its source.
  `default Stream<E>`
  `stream()`
  Returns a sequential `Stream` with this collection as its source.
  `default <T> T[]`
  `toArray(IntFunction<T[]> generator)`
  Returns an array containing all of the elements in this collection, using the provided `generator` function to allocate the returned array.

  ### Methods declared in interface List

  `addFirst, addLast, getFirst, getLast, removeFirst, removeLast, reversed, sort`
  Modifier and Type
  Method
  Description
  `default void`
  `addFirst(E e)`
  Adds an element as the first element of this collection (optional operation).
  `default void`
  `addLast(E e)`
  Adds an element as the last element of this collection (optional operation).
  `default E`
  `getFirst()`
  Gets the first element of this collection.
  `default E`
  `getLast()`
  Gets the last element of this collection.
  `default E`
  `removeFirst()`
  Removes and returns the first element of this collection (optional operation).
  `default E`
  `removeLast()`
  Removes and returns the last element of this collection (optional operation).
  `default List<E>`
  `reversed()`
  Returns a reverse-ordered view of this collection.
  `default void`
  `sort(Comparator<? super E> c)`
  Sorts this list according to the order induced by the specified `Comparator` (optional operation).

- ## Constructor Details

  - ### Stack

    public Stack()
    Creates an empty Stack.

- ## Method Details

  - ### push

    public E push(E item)
    Pushes an item onto the top of this stack. This has exactly the same effect as:

    >     addElement(item)

    Parameters:
      `item` - the item to be pushed onto this stack.
    Returns:
      the `item` argument.
    See Also:
      - `Vector.addElement(E)`

  - ### pop

    public E 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 (the last item of the `Vector` object).
    Throws:
      `EmptyStackException` - if this stack is empty.

  - ### peek

    public E 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 (the last item of the `Vector` object).
    Throws:
      `EmptyStackException` - if this stack is empty.

  - ### empty

    public boolean empty()
    Tests if this stack is empty.
    Returns:
      `true` if and only if this stack contains no items; `false` otherwise.

  - ### search

    public int search(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 from the top of the stack where the object is located; the return value `-1` indicates that the object is not on the stack.