Package org.apache.commons.collections4.iterators

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 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().