Package org.apache.commons.collections4.iterators

Class PeekingIterator<E>

  • Type Parameters:
    E - the type of elements returned by this iterator.
    All Implemented Interfaces:
    java.util.Iterator<E>
    public class PeekingIterator<E>
extends java.lang.Object
implements java.util.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​(java.util.Iterator<? extends E> iterator)
      Constructs a new instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      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​(java.util.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 Detail

      • PeekingIterator

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

    • Method Detail

      • peekingIterator

        public static <E> PeekingIterator<E> peekingIterator​(java.util.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:
        java.lang.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:
        java.util.NoSuchElementException - if the iterator is already exhausted according to hasNext()

      • hasNext

        public boolean hasNext()
        Specified by:
        hasNext in interface java.util.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 java.util.Iterator<E>
        Returns:
        the next element from the iterator
        Throws:
        java.util.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 java.util.Iterator<E>
        Throws:
        java.lang.IllegalStateException - if peek() or element() has been called prior to the call to remove().