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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private boolean
    exhausted
    Indicates that the decorated iterator is exhausted.
    private final Iterator<? extends E>
    iterator
    The iterator being decorated.
    private E
    slot
    The current slot for lookahead.
    private boolean
    slotFilled
    Indicates if the lookahead slot is filled.

  • 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.
    private void
    fill()
     
    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

  • Field Details

    • iterator

      private final Iterator<? extends E> iterator
      The iterator being decorated.

    • exhausted

      private boolean exhausted
      Indicates that the decorated iterator is exhausted.

    • slotFilled

      private boolean slotFilled
      Indicates if the lookahead slot is filled.

    • slot

      private E slot
      The current slot for lookahead.

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

    • fill

      private void fill()

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