com.google.common.collect
Class Iterators

java.lang.Object
  extended by com.google.common.collect.Iterators

public final class Iterators
extends java.lang.Object

This class contains static utility methods that operate on or return objects of type Iterator. Also see the parallel implementations in Iterables.

Author:
Kevin Bourrillion, Scott Bonneau

Method Summary
static
<T> boolean
addAll(java.util.Collection<T> collection, java.util.Iterator<? extends T> iterator)
          Adds all elements in iterator to collection.
static
<T> boolean
all(java.util.Iterator<T> iterator, Predicate<? super T> predicate)
          Returns true if every element returned by iterator satisfies the given predicate.
static
<T> boolean
any(java.util.Iterator<T> iterator, Predicate<? super T> predicate)
          Returns true if one or more elements returned by iterator satisfy the given predicate.
static
<T> java.util.Enumeration<T>
asEnumeration(java.util.Iterator<T> iterator)
          Adapts an Iterator to the Enumeration interface.
static
<T> java.util.Iterator<T>
concat(java.util.Iterator<? extends java.util.Iterator<? extends T>> iterators)
          Combines multiple iterators into a single iterator.
static
<T> java.util.Iterator<T>
concat(java.util.Iterator<? extends T>... iterators)
          Combines multiple iterators into a single iterator.
static
<T> java.util.Iterator<T>
concat(java.util.Iterator<? extends T> a, java.util.Iterator<? extends T> b)
          Combines two iterators into a single iterator.
static
<T> java.util.Iterator<T>
cycle(java.lang.Iterable<T> iterable)
          Returns an iterator that cycles indefinitely over the elements of iterable.
static
<T> java.util.Iterator<T>
cycle(T... elements)
          Returns an iterator that cycles indefinitely over the provided elements.
static boolean elementsEqual(java.util.Iterator<?> iterator1, java.util.Iterator<?> iterator2)
          Determines whether two iterators contain equal elements.
static
<T> java.util.Iterator<T>
emptyIterator()
          Returns the empty Iterator.
static
<T> java.util.ListIterator<T>
emptyListIterator()
          Returns the empty ListIterator.
static
<T> java.util.Iterator<T>
filter(java.util.Iterator<?> unfiltered, java.lang.Class<T> type)
          Returns all instances of class type in unfiltered.
static
<T> java.util.Iterator<T>
filter(java.util.Iterator<T> unfiltered, Predicate<? super T> predicate)
          Returns the elements of unfiltered that satisfy a predicate.
static
<E> E
find(java.util.Iterator<E> iterator, Predicate<? super E> predicate)
          Returns the first element in iterator that satisfies the given predicate.
static
<T> java.util.Iterator<T>
forEnumeration(java.util.Enumeration<T> enumeration)
          Adapts an Enumeration to the Iterator interface.
static int frequency(java.util.Iterator<?> iterator, java.lang.Object element)
          Returns the number of elements in the specified iterator equal to the specified object.
static
<T> T
getLast(java.util.Iterator<T> iterator)
          Advances iterator to the end, returning the last element.
static
<T> T
getOnlyElement(java.util.Iterator<T> iterator)
          Returns the single element contained in iterator.
static
<T> T
getOnlyElement(java.util.Iterator<T> iterator, T defaultValue)
          Returns the single element contained in iterator, or defaultValue if the iterator is empty.
static
<T> java.util.Iterator<T>
limit(java.util.Iterator<T> iterator, int limit)
          Creates an iterator returning the first limit elements of the given iterator.
static
<T> T[]
newArray(java.util.Iterator<T> iterator, java.lang.Class<T> type)
          Converts an iterator into an array.
static
<T> java.util.Iterator<java.util.Iterator<T>>
partition(java.util.Iterator<? extends T> iterator, int partitionSize, boolean padToSize)
          Partition an iterator into sub-iterators of the given size like so: {A, B, C, D, E, F} with partition size 3 => {A, B, C} and {D, E, F}.
static
<T> PeekingIterator<T>
peekingIterator(java.util.Iterator<T> iterator)
          Wraps the supplied iterator in a PeekingIterator.
static int size(java.util.Iterator<?> iterator)
          Returns the number of elements remaining in iterator.
static
<T> int
skip(java.util.Iterator<T> iterator, int numberToSkip)
          Calls next() on iterator, either numberToSkip times or until hasNext() returns false, whichever comes first.
static java.lang.String toString(java.util.Iterator<?> iterator)
          Returns a string representation of the elements in iterator, with the format "[e1, e2, ..., en]".
static
<F,T> java.util.Iterator<T>
transform(java.util.Iterator<F> fromIterator, Function<? super F,? extends T> function)
          Returns an iterator that applies function to each element of fromIterator.
static
<T> java.util.Iterator<T>
unmodifiableIterator(java.util.Iterator<T> iterator)
          Returns an unmodifiable view of iterator.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

emptyIterator

public static <T> java.util.Iterator<T> emptyIterator()
Returns the empty Iterator.


emptyListIterator

public static <T> java.util.ListIterator<T> emptyListIterator()
Returns the empty ListIterator.


unmodifiableIterator

public static <T> java.util.Iterator<T> unmodifiableIterator(java.util.Iterator<T> iterator)
Returns an unmodifiable view of iterator.


size

public static int size(java.util.Iterator<?> iterator)
Returns the number of elements remaining in iterator. The iterator will be left exhausted: its hasNext() method will return false.


elementsEqual

public static boolean elementsEqual(java.util.Iterator<?> iterator1,
                                    java.util.Iterator<?> iterator2)
Determines whether two iterators contain equal elements. More specifically, this method returns true if iterator1 and iterator2 contain the same number of elements and every element of iterator1 is equal to the corresponding element of iterator2.

Note that this will modify the supplied iterators, since they will have been advanced some number of elements forward.


toString

public static java.lang.String toString(java.util.Iterator<?> iterator)
Returns a string representation of the elements in iterator, with the format "[e1, e2, ..., en]". The iterator will be left exhausted: its hasNext() method will return false.


getOnlyElement

public static <T> T getOnlyElement(java.util.Iterator<T> iterator)
Returns the single element contained in iterator.

Throws:
java.util.NoSuchElementException - if the iterator is empty
java.lang.IllegalArgumentException - if the iterator contains multiple elements

getOnlyElement

public static <T> T getOnlyElement(java.util.Iterator<T> iterator,
                                   @Nullable
                                   T defaultValue)
Returns the single element contained in iterator, or defaultValue if the iterator is empty.

Throws:
java.lang.IllegalArgumentException - if the iterator contains multiple elements

newArray

public static <T> T[] newArray(java.util.Iterator<T> iterator,
                               java.lang.Class<T> type)
Converts an iterator into an array. The iterator will be left exhausted: its hasNext() method will return false.

Parameters:
iterator - the iterator to convert
type - the type of the elements
Returns:
a newly-allocated array into which all the elements of the iterator have been copied. It may be empty, but it never will be null.

addAll

public static <T> boolean addAll(java.util.Collection<T> collection,
                                 java.util.Iterator<? extends T> iterator)
Adds all elements in iterator to collection. The iterator will be left exhausted: its hasNext() method will return false.

Returns:
true if collection was modified as a result of this operation

frequency

public static int frequency(java.util.Iterator<?> iterator,
                            @Nullable
                            java.lang.Object element)
Returns the number of elements in the specified iterator equal to the specified object. The iterator will be left exhausted: its hasNext() method will return false.

See Also:
Collections.frequency(java.util.Collection, java.lang.Object)

cycle

public static <T> java.util.Iterator<T> cycle(java.lang.Iterable<T> iterable)
Returns an iterator that cycles indefinitely over the elements of iterable.

The returned iterator supports remove() if the provided iterator does. After remove() is called, subsequent cycles omit the removed element, which is no longer in iterable. The iterator's hasNext() method returns true until iterable is empty.

Warning: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit break or be certain that you will eventually remove all the elements.


cycle

public static <T> java.util.Iterator<T> cycle(T... elements)
Returns an iterator that cycles indefinitely over the provided elements.

The returned iterator supports remove() if the provided iterator does. After calling remove(), subsequent cycles omit the removed element, but elements does not change. The iterator's hasNext() method returns true until all of the original elements have been removed.

Warning: Typical uses of the resulting iterator may produce an infinite loop. You should use an explicit break or be certain that you will eventually remove all the elements.


concat

public static <T> java.util.Iterator<T> concat(java.util.Iterator<? extends T> a,
                                               java.util.Iterator<? extends T> b)
Combines two iterators into a single iterator. The returned iterator iterates across the elements in a, followed by the elements in b. The source iterators are not polled until necessary.

The returned iterator supports remove() when the appropriate source iterator supports it.


concat

public static <T> java.util.Iterator<T> concat(java.util.Iterator<? extends T>... iterators)
Combines multiple iterators into a single iterator. The returned iterator iterates across the elements in each source iterator. The source iterators are not polled until necessary.

The returned iterator supports remove() when the appropriate source iterator supports it.

Throws:
java.lang.NullPointerException - if any of the provided iterators is null

concat

public static <T> java.util.Iterator<T> concat(java.util.Iterator<? extends java.util.Iterator<? extends T>> iterators)
Combines multiple iterators into a single iterator. The returned iterator iterates across the elements in each source iterator. The source iterators are not polled until necessary.

The returned iterator supports Iterator.remove() when the appropriate source iterator supports it. The methods of the returned iterator may throw NullPointerException if any of the source iterators are null.


partition

public static <T> java.util.Iterator<java.util.Iterator<T>> partition(java.util.Iterator<? extends T> iterator,
                                                                      int partitionSize,
                                                                      boolean padToSize)
Partition an iterator into sub-iterators of the given size like so: {A, B, C, D, E, F} with partition size 3 => {A, B, C} and {D, E, F}. The returned iterator does not support remove().

After you call next() on the returned iterator, the iterators from prior next() calls become invalid.

Parameters:
iterator - the iterator to partition
partitionSize - the size of each partition
padToSize - whether to pad the last partition to the partition size with null
Returns:
an iterator across partitioned iterators

filter

public static <T> java.util.Iterator<T> filter(java.util.Iterator<T> unfiltered,
                                               Predicate<? super T> predicate)
Returns the elements of unfiltered that satisfy a predicate. It may return an empty iterator, but never null. The resulting iterator does not support remove().


filter

public static <T> java.util.Iterator<T> filter(java.util.Iterator<?> unfiltered,
                                               java.lang.Class<T> type)
Returns all instances of class type in unfiltered. The returned iterator has elements whose class is type or a subclass of type. The returned iterator does not support remove().

Parameters:
unfiltered - an iterator containing objects of any type
type - the type of elements desired
Returns:
an unmodifiable iterator containing all elements of the original iterator that were of the requested type

any

public static <T> boolean any(java.util.Iterator<T> iterator,
                              Predicate<? super T> predicate)
Returns true if one or more elements returned by iterator satisfy the given predicate.


all

public static <T> boolean all(java.util.Iterator<T> iterator,
                              Predicate<? super T> predicate)
Returns true if every element returned by iterator satisfies the given predicate. If iterator is empty, true is returned.


find

public static <E> E find(java.util.Iterator<E> iterator,
                         Predicate<? super E> predicate)
Returns the first element in iterator that satisfies the given predicate. If a matching element is found, the iterator will be left in a state such that calling iterator.remove() will remove the found item. If no such element is found, the iterator will be left exhausted: its hasNext() method will return false.

Returns:
the first matching element in iterator
Throws:
java.util.NoSuchElementException - if no element in iterator matches the given predicate

transform

public static <F,T> java.util.Iterator<T> transform(java.util.Iterator<F> fromIterator,
                                                    Function<? super F,? extends T> function)
Returns an iterator that applies function to each element of fromIterator.

The returned iterator supports remove() if the provided iterator does. After a successful remove() call, fromIterator no longer contains the corresponding element.


getLast

public static <T> T getLast(java.util.Iterator<T> iterator)
Advances iterator to the end, returning the last element.

Returns:
the last element of iterator
Throws:
java.util.NoSuchElementException - if the iterator has no remaining elements

skip

public static <T> int skip(java.util.Iterator<T> iterator,
                           int numberToSkip)
Calls next() on iterator, either numberToSkip times or until hasNext() returns false, whichever comes first.

Returns:
the number of elements skipped

forEnumeration

public static <T> java.util.Iterator<T> forEnumeration(java.util.Enumeration<T> enumeration)
Adapts an Enumeration to the Iterator interface. The returned iterator does not support remove().


asEnumeration

public static <T> java.util.Enumeration<T> asEnumeration(java.util.Iterator<T> iterator)
Adapts an Iterator to the Enumeration interface.

See Also:
Collections.enumeration(Collection)

limit

public static <T> java.util.Iterator<T> limit(java.util.Iterator<T> iterator,
                                              int limit)
Creates an iterator returning the first limit elements of the given iterator. If the original iterator does not contain that many elements, the returned iterator will have the same behavior as the original iterator. The returned iterator supports remove() if the original iterator supports it.

Parameters:
iterator - the iterator to limit
limit - the maximum number of elements in the returned iterator
Throws:
java.lang.IllegalArgumentException - if limit is negative

peekingIterator

public static <T> PeekingIterator<T> peekingIterator(java.util.Iterator<T> iterator)
Wraps the supplied iterator in a PeekingIterator. The PeekingIterator assumes ownership of the supplied iterator, so users should cease making direct calls to it after calling this method.

If the PeekingIterator.peek() method of the constructed PeekingIterator is never called, the returned iterator will behave exactly the same as the supplied iterator.

Subsequent calls to peek() with no intervening calls to next() do not affect the iteration, and hence return the same object each time. After a call to peek(), the next call to next() is guaranteed to return the same object that the peek() call returned. For example:

   PeekingIterator<E> peekingIterator = ...;
   // Either the next three calls will each throw
   // NoSuchElementExceptions, or...
   E e1 = peekingIterator.peek();
   E e2 = peekingIterator.peek(); // e2 is the same as e1
   E e3 = peekingIterator.next(); // e3 is the same as e1/e2
 

Calling Iterator.remove() after PeekingIterator.peek() is unsupported by the returned iterator and will throw an IllegalStateException.



Copyright © 2008 Google. All Rights Reserved.