Package org.apache.commons.collections4.iterators

# Class PushbackIterator<E>

java.lang.Object
org.apache.commons.collections4.iterators.PushbackIterator<E>

Type Parameters:
  `E` - The type of elements returned by this iterator.

All Implemented Interfaces:
  `Iterator<E>`

public class PushbackIterator<E> extends Object implements Iterator<E>
Decorates an iterator to support pushback of elements.

The decorator stores the pushed back elements in a LIFO manner: the last element that has been pushed back, will be returned as the next element in a call to `next()`.

The decorator does not support the removal operation. Any call to `remove()` will result in an `UnsupportedOperationException`.

Since:
  4.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PushbackIterator(Iterator<? extends E> iterator)`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `hasNext()`
  `E`
  `next()`
  `void`
  `pushback(E item)`
  Push back the given element to the iterator.
  `static <E> PushbackIterator<E>`
  `pushbackIterator(Iterator<? extends E> iterator)`
  Decorates the specified iterator to support one-element lookahead.
  `void`
  `remove()`
  Always throws `UnsupportedOperationException`.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.util.Iterator

  `forEachRemaining`

- ## Constructor Details

  - ### PushbackIterator

    public PushbackIterator(Iterator<? extends E> iterator)
    Constructs a new instance.
    Parameters:
      `iterator` - The iterator to decorate

- ## Method Details

  - ### pushbackIterator

    public static <E> PushbackIterator<E> pushbackIterator(Iterator<? extends E> iterator)
    Decorates the specified iterator to support one-element lookahead.

    If the iterator is already a `PushbackIterator` it is returned directly.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterator` - The iterator to decorate
    Returns:
      A new peeking iterator
    Throws:
      `NullPointerException` - if the iterator is null

  - ### hasNext

    public boolean hasNext()
    Specified by:
      `hasNext` in interface `Iterator<E>`

  - ### next

    public E next()
    Specified by:
      `next` in interface `Iterator<E>`

  - ### pushback

    public void pushback(E item)
    Push back the given element to the iterator.

    Calling `next()` immediately afterwards will return exactly this element.

    Parameters:
      `item` - The element to push back to the iterator

  - ### remove

    public void remove()
    Always throws `UnsupportedOperationException`.
    Specified by:
      `remove` in interface `Iterator<E>`
    Throws:
      `UnsupportedOperationException` - Always thrown.