org.apache.commons.collections4.iterators
Class PeekingIterator<E>

java.lang.Object
  org.apache.commons.collections4.iterators.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

Version:

$Id: PeekingIterator.java 1479760 2013-05-07 05:12:06Z tn $

PeekingIterator

public PeekingIterator(Iterator<? extends E> iterator)

Constructor.

Parameters:

iterator - the iterator to decorate

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:

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

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