Package org.apache.commons.collections4.iterators

Class PeekingIterator<E>

  • 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 Detail

      • PeekingIterator

        public PeekingIterator​(Iterator<? extends E> iterator)
        Constructor.
        Parameters:
        iterator - the iterator to decorate

    • Method Detail

      • 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

      • hasNext

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

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

        Returns:
        the next element from the iterator

      • 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.
        Returns:
        the next element from the iterator
        Throws:
        NoSuchElementException - if the iterator is already exhausted according to hasNext()

      • next

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