com.google.common.collect
Class Iterators

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

public final class Iterators
extends 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(Collection<T> collection, Iterator<? extends T> iterator) Adds all elements in iterator to collection.
static <T> boolean	all(Iterator<T> iterator, Predicate<? super T> predicate) Returns true if no element returned by iterator evaluates to false under predicate.
static <T> boolean	any(Iterator<T> iterator, Predicate<? super T> predicate) Returns true if some element returned by iterator evaluates to true under predicate.
static <T> Enumeration<T>	asEnumeration(Iterator<T> iterator) Adapts an Iterator to the Enumeration interface.
static <T> Iterator<T>	concat(Iterator<? extends Iterator<? extends T>> iterators) Concatenates multiple iterators into a single iterator.
static <T> Iterator<T>	concat(Iterator<? extends T>... iterators) Varargs form of #concat(Iterator).
static <T> Iterator<T>	concat(Iterator<? extends T> a, Iterator<? extends T> b) Two-argument form of #concat(Iterator).
static <T> Iterator<T>	cycle(Iterable<T> iterable) Returns an iterator that cycles indefinitely over the elements of iterable until it is empty.
static <T> Iterator<T>	cycle(T... elements) Variant of #cycle(Iterable) accepting varargs parameters.
static boolean	elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2) Determines whether two iterators contain equal elements.
static <T> Iterator<T>	emptyIterator() Returns the empty Iterator.
static <T> Iterator<T>	filter(Iterator<?> unfiltered, Class<T> type) Returns all instances of type found in unfiltered.
static <T> Iterator<T>	filter(Iterator<T> unfiltered, Predicate<? super T> predicate) Returns the elements of unfiltered for which predicate evaluates to true.
static <E> E	find(Iterator<E> iterator, Predicate<? super E> predicate) Returns the first element in iterator for which the given predicate matches.
static <T> Iterator<T>	forEnumeration(Enumeration<T> enumeration) Adapts an Enumeration to the Iterator interface.
static int	frequency(Iterator<?> iterator, Object element) Variant of Collections#frequency for iterators.
static <T> T	getOnlyElement(Iterator<T> iterator) Returns the single element contained in iterator.
static <T> T	getOnlyElement(Iterator<T> iterator, T defaultValue) Returns the single element contained in iterator, or defaultValue if the iterator is empty.
static <T> T[]	newArray(Iterator<T> iterator, Class<T> type) Converts an Iterator into an array.
static <T> Iterator<Iterator<T>>	partition(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 String	toString(Iterator<?> iterator) Returns a string representation of the elements in iterator, in the format "[e1, e2, ..., en]".
static <F,T> Iterator<T>	transform(Iterator<F> fromIterator, Function<? super F,? extends T> function) Returns an iterator that applies function to each element of fromIterator.
static <T> Iterator<T>	unmodifiableIterator(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> Iterator<T> emptyIterator()

Returns the empty Iterator.

unmodifiableIterator

public static <T> Iterator<T> unmodifiableIterator(Iterator<T> iterator)

Returns an unmodifiable view of iterator.

elementsEqual

public static boolean elementsEqual(Iterator<?> iterator1,
                                    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 actually modify the supplied iterators such that they will not be usable after calling this method (they will have been advanced some number of elements forward).

toString

public static String toString(Iterator<?> iterator)

Returns a string representation of the elements in iterator, in the format "[e1, e2, ..., en]".

getOnlyElement

public static <T> T getOnlyElement(Iterator<T> iterator)

Returns the single element contained in iterator.

Throws:

NoSuchElementException - if the iterator is empty

IllegalArgumentException - if the iterator contains multiple elements

getOnlyElement

public static <T> T getOnlyElement(Iterator<T> iterator,
                                   @Nullable
                                   T defaultValue)

Returns the single element contained in iterator, or defaultValue if the iterator is empty.

Throws:

IllegalArgumentException - if the iterator contains multiple elements

newArray

public static <T> T[] newArray(Iterator<T> iterator,
                               Class<T> type)

Converts an Iterator into an array.

Parameters:

iterator - any instance of Iterator (will not be modified)

type - the type of the elements

Returns:

a newly-allocated array into which all the elements of the iterator have been copied. May be empty but never null.

addAll

public static <T> boolean addAll(Collection<T> collection,
                                 Iterator<? extends T> iterator)

Adds all elements in iterator to collection.

Returns:

true if collection was modified as a result of this operation.

frequency

public static int frequency(Iterator<?> iterator,
                            @Nullable
                            Object element)

Variant of Collections#frequency for iterators.

cycle

public static <T> Iterator<T> cycle(Iterable<T> iterable)

Returns an iterator that cycles indefinitely over the elements of iterable until it 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> Iterator<T> cycle(T... elements)

Variant of #cycle(Iterable) accepting varargs parameters.

concat

public static <T> Iterator<T> concat(Iterator<? extends T> a,
                                     Iterator<? extends T> b)

Two-argument form of #concat(Iterator).

concat

public static <T> Iterator<T> concat(Iterator<? extends T>... iterators)

Varargs form of #concat(Iterator).

concat

public static <T> Iterator<T> concat(Iterator<? extends Iterator<? extends T>> iterators)

Concatenates multiple iterators into a single iterator. No references are copied, and the source iterators are never polled until necessary.

The returned iterator supports Iterator.remove() when and only 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> Iterator<Iterator<T>> partition(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}.

NOTE: You must read partitions one at a time from the returned iterator Once you read forward any iterators from previous partitions will 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 of partitioned iterators

filter

public static <T> Iterator<T> filter(Iterator<T> unfiltered,
                                     Predicate<? super T> predicate)

Returns the elements of unfiltered for which predicate evaluates to true. May return an empty iterator, but never null. The resulting iterator does not support Iterator.remove().

filter

public static <T> Iterator<T> filter(Iterator<?> unfiltered,
                                     Class<T> type)

Returns all instances of type found in unfiltered. Similar to filter(Iterator,Predicate).

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(Iterator<T> iterator,
                              Predicate<? super T> predicate)

Returns true if some element returned by iterator evaluates to true under predicate. Returns false if iterator is empty.

all

public static <T> boolean all(Iterator<T> iterator,
                              Predicate<? super T> predicate)

Returns true if no element returned by iterator evaluates to false under predicate. Returns true if iterator is empty.

find

public static <E> E find(Iterator<E> iterator,
                         Predicate<? super E> predicate)

Returns the first element in iterator for which the given predicate matches. 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 such that iterator.hasNext() returns false.

Returns:

the first matching element in iterator

Throws:

NoSuchElementException - if no element in iterator matches the given predicate

transform

public static <F,T> Iterator<T> transform(Iterator<F> fromIterator,
                                          Function<? super F,? extends T> function)

Returns an iterator that applies function to each element of fromIterator.

forEnumeration

public static <T> Iterator<T> forEnumeration(Enumeration<T> enumeration)

Adapts an Enumeration to the Iterator interface.

asEnumeration

public static <T> Enumeration<T> asEnumeration(Iterator<T> iterator)

Adapts an Iterator to the Enumeration interface.

See Also:

Collections.enumeration(Collection)