org.apache.commons.collections4.iterators

Class PeekingIterator<E>

java.lang.Object

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

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 and Description
PeekingIterator(java.util.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(java.util.Iterator<? extends E> iterator) Decorates the specified iterator to support one-element lookahead.
void	remove()

Methods inherited from class java.lang.Object

equals, 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)

Constructor.

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

hasNext

public boolean hasNext()

Specified by:

hasNext in interface java.util.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:

java.util.NoSuchElementException - if the iterator is already exhausted according to hasNext()

next

public E next()

Specified by:

next in interface java.util.Iterator<E>

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