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

Constructor Summary

Constructors

Constructor and Description
PeekingIterator(Iterator<? extends E> iterator) Constructor.

Method Summary

Modifier and Type	Method and Description
E	element() Returns the next element in iteration without advancing the underlying iterator.
boolean	hasNext()
E	next()
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

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>

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