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

java.lang.Object
  extended by 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 $

Constructor Summary
PeekingIterator(Iterator<? extends E> iterator)
          Constructor.
 
Method Summary
 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
 

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


Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.