# Class PeekingIterator<E>

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

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

All Implemented Interfaces:
  `Iterator<E>`

public class PeekingIterator<E> extends Object implements Iterator<E>
Decorates an iterator to support one-element lookahead while iterating.

The decorator supports the removal operation, but an `IllegalStateException` will be thrown if `remove()` is called directly after a call to `peek()` or `element()`.

Since:
  4.0

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `E`
  `element()`
  Returns the next element in iteration without advancing the underlying iterator.
  `boolean`
  `hasNext()`
  `E`
  `next()`
  Returns the next element in iteration.
  `E`
  `peek()`
  Returns the next element in iteration without advancing the underlying iterator.
  `static <E> PeekingIterator<E>`
  `peekingIterator(Iterator<? extends E> iterator)`
  Decorates the specified iterator to support one-element lookahead.
  `void`
  `remove()`

  ### 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

  - ### PeekingIterator

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

- ## Method Details

  - ### peekingIterator

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

    If the iterator is already a `PeekingIterator` 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

  - ### element

    public E element()
    Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.

    Note that if the underlying iterator is a `FilterIterator` or a `FilterListIterator`, the underlying predicate will not be tested if element() or `peek()` has been called after the most recent invocation of `next()`

    Returns:
      the next element from the iterator
    Throws:
      `NoSuchElementException` - if the iterator is already exhausted according to `hasNext()`

  - ### hasNext

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

  - ### next

    public E next()
    Returns the next element in iteration.

    Note that if the underlying iterator is a `FilterIterator` or a `FilterListIterator`, the underlying predicate will not be tested if `element()` or `peek()` has been called after the most recent invocation of `next()`.

    Specified by:
      `next` in interface `Iterator<E>`
    Returns:
      the next element from the iterator
    Throws:
      `NoSuchElementException` - if the iterator is already exhausted according to `hasNext()`.

  - ### peek

    public E peek()
    Returns the next element in iteration without advancing the underlying iterator. If the iterator is already exhausted, null will be returned.

    Note: this method does not throw a `NoSuchElementException` if the iterator is already exhausted. If you want such a behavior, use `element()` instead.

    The rationale behind this is to follow the `Queue` interface which uses the same terminology.

    Note that if the underlying iterator is a `FilterIterator` or a `FilterListIterator`, the underlying predicate will not be tested if `element()` or peek() has been called after the most recent invocation of `next()`.

    Returns:
      the next element from the iterator

  - ### remove

    public void remove()
    Specified by:
      `remove` in interface `Iterator<E>`
    Throws:
      `IllegalStateException` - if `peek()` or `element()` has been called prior to the call to `remove()`.