com.google.common.collect
Class Iterators

java.lang.Object
  extended by 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. Except as noted, each method has a corresponding Iterable-based method in the Iterables class.

Author:
Kevin Bourrillion, Jared Levy

Method Summary
static
<T> boolean
addAll(Collection<T> addTo, 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 every element returned by iterator satisfies the given predicate.
static
<T> boolean
any(Iterator<T> iterator, Predicate<? super T> predicate)
          Returns true if one or more elements returned by iterator satisfy the given 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>> inputs)
          Combines multiple iterators into a single iterator.
static
<T> Iterator<T>
concat(Iterator<? extends T>... inputs)
          Combines multiple iterators into a single iterator.
static
<T> Iterator<T>
concat(Iterator<? extends T> a, Iterator<? extends T> b)
          Combines two iterators into a single iterator.
static
<T> Iterator<T>
concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c)
          Combines three iterators into a single iterator.
static
<T> Iterator<T>
concat(Iterator<? extends T> a, Iterator<? extends T> b, Iterator<? extends T> c, Iterator<? extends T> d)
          Combines four iterators into a single iterator.
static boolean contains(Iterator<?> iterator, Object element)
          Returns true if iterator contains element.
static
<T> Iterator<T>
cycle(Iterable<T> iterable)
          Returns an iterator that cycles indefinitely over the elements of iterable.
static
<T> Iterator<T>
cycle(T... elements)
          Returns an iterator that cycles indefinitely over the provided elements.
static boolean elementsEqual(Iterator<?> iterator1, Iterator<?> iterator2)
          Determines whether two iterators contain equal elements in the same order.
static
<T> UnmodifiableIterator<T>
emptyIterator()
          Returns the empty iterator.
static
<T> UnmodifiableIterator<T>
filter(Iterator<?> unfiltered, Class<T> type)
          Returns all instances of class type in unfiltered.
static
<T> UnmodifiableIterator<T>
filter(Iterator<T> unfiltered, Predicate<? super T> predicate)
          Returns the elements of unfiltered that satisfy a predicate.
static
<T> T
find(Iterator<T> iterator, Predicate<? super T> predicate)
          Returns the first element in iterator that satisfies the given predicate.
static
<T> UnmodifiableIterator<T>
forArray(T... array)
          Returns an iterator containing the elements of array in order.
static
<T> UnmodifiableIterator<T>
forEnumeration(Enumeration<T> enumeration)
          Adapts an Enumeration to the Iterator interface.
static int frequency(Iterator<?> iterator, Object element)
          Returns the number of elements in the specified iterator that equal the specified object.
static
<T> T
get(Iterator<T> iterator, int position)
          Advances iterator position + 1 times, returning the element at the positionth position.
static
<T> T
getLast(Iterator<T> iterator)
          Advances iterator to the end, returning the last element.
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> UnmodifiableIterator<List<T>>
paddedPartition(Iterator<T> iterator, int size)
          Divides an iterator into unmodifiable sublists of the given size, padding the final iterator with null values if necessary.
static
<T> UnmodifiableIterator<List<T>>
partition(Iterator<T> iterator, int size)
          Divides an iterator into unmodifiable sublists of the given size (the final list may be smaller).
static
<T> PeekingIterator<T>
peekingIterator(Iterator<? extends T> iterator)
          Returns a PeekingIterator backed by the given iterator.
static boolean removeAll(Iterator<?> removeFrom, Collection<?> elementsToRemove)
          Traverses an iterator and removes every element that belongs to the provided collection.
static boolean retainAll(Iterator<?> removeFrom, Collection<?> elementsToRetain)
          Traverses an iterator and removes every element that does not belong to the provided collection.
static
<T> UnmodifiableIterator<T>
singletonIterator(T value)
          Returns an iterator containing only value.
static int size(Iterator<?> iterator)
          Returns the number of elements remaining in iterator.
static
<T> T[]
toArray(Iterator<? extends T> iterator, Class<T> type)
          Copies an iterator's elements into an array.
static String toString(Iterator<?> iterator)
          Returns a string representation of iterator, with 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> UnmodifiableIterator<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> UnmodifiableIterator<T> emptyIterator()
Returns the empty iterator.

The Iterable equivalent of this method is Collections.emptySet().


unmodifiableIterator

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


size

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


contains

public static boolean contains(Iterator<?> iterator,
                               @Nullable
                               Object element)
Returns true if iterator contains element.


removeAll

public static boolean removeAll(Iterator<?> removeFrom,
                                Collection<?> elementsToRemove)
Traverses an iterator and removes every element that belongs to the provided collection. The iterator will be left exhausted: its hasNext() method will return false.

Parameters:
removeFrom - the iterator to (potentially) remove elements from
elementsToRemove - the elements to remove
Returns:
true if any elements are removed from iterator

retainAll

public static boolean retainAll(Iterator<?> removeFrom,
                                Collection<?> elementsToRetain)
Traverses an iterator and removes every element that does not belong to the provided collection. The iterator will be left exhausted: its hasNext() method will return false.

Parameters:
removeFrom - the iterator to (potentially) remove elements from
elementsToRetain - the elements to retain
Returns:
true if any elements are removed from iterator

elementsEqual

public static boolean elementsEqual(Iterator<?> iterator1,
                                    Iterator<?> iterator2)
Determines whether two iterators contain equal elements in the same order. 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 String toString(Iterator<?> iterator)
Returns a string representation of 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(Iterator<T> iterator)
Returns the single element contained in iterator.

Throws:
NoSuchElementException - if the iterator is empty
IllegalArgumentException - if the iterator contains multiple elements. The state of the iterator is unspecified.

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. The state of the iterator is unspecified.

toArray

public static <T> T[] toArray(Iterator<? extends T> iterator,
                              Class<T> type)
Copies an iterator's elements into an array. The iterator will be left exhausted: its hasNext() method will return false.

Parameters:
iterator - the iterator to copy
type - the type of the elements
Returns:
a newly-allocated array into which all the elements of the iterator have been copied

addAll

public static <T> boolean addAll(Collection<T> addTo,
                                 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(Iterator<?> iterator,
                            @Nullable
                            Object element)
Returns the number of elements in the specified iterator that equal 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> Iterator<T> cycle(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> 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 remove() is called, 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> Iterator<T> concat(Iterator<? extends T> a,
                                     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 corresponding input iterator supports it.


concat

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

The returned iterator supports remove() when the corresponding input iterator supports it.


concat

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

The returned iterator supports remove() when the corresponding input iterator supports it.


concat

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

The returned iterator supports remove() when the corresponding input iterator supports it.

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

concat

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

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


partition

public static <T> UnmodifiableIterator<List<T>> partition(Iterator<T> iterator,
                                                          int size)
Divides an iterator into unmodifiable sublists of the given size (the final list may be smaller). For example, partitioning an iterator containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e]] -- an outer iterator containing two inner lists of three and two elements, all in the original order.

The returned lists implement RandomAccess.

Parameters:
iterator - the iterator to return a partitioned view of
size - the desired size of each partition (the last may be smaller)
Returns:
an iterator of immutable lists containing the elements of iterator divided into partitions
Throws:
IllegalArgumentException - if size is nonpositive

paddedPartition

public static <T> UnmodifiableIterator<List<T>> paddedPartition(Iterator<T> iterator,
                                                                int size)
Divides an iterator into unmodifiable sublists of the given size, padding the final iterator with null values if necessary. For example, partitioning an iterator containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e, null]] -- an outer iterator containing two inner lists of three elements each, all in the original order.

The returned lists implement RandomAccess.

Parameters:
iterator - the iterator to return a partitioned view of
size - the desired size of each partition
Returns:
an iterator of immutable lists containing the elements of iterator divided into partitions (the final iterable may have trailing null elements)
Throws:
IllegalArgumentException - if size is nonpositive

filter

public static <T> UnmodifiableIterator<T> filter(Iterator<T> unfiltered,
                                                 Predicate<? super T> predicate)
Returns the elements of unfiltered that satisfy a predicate.


filter

public static <T> UnmodifiableIterator<T> filter(Iterator<?> unfiltered,
                                                 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.

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 one or more elements returned by iterator satisfy the given predicate.


all

public static <T> boolean all(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 <T> T find(Iterator<T> iterator,
                         Predicate<? super T> 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:
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.

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


get

public static <T> T get(Iterator<T> iterator,
                        int position)
Advances iterator position + 1 times, returning the element at the positionth position.

Parameters:
position - position of the element to return
Returns:
the element at the specified position in iterator
Throws:
IndexOutOfBoundsException - if position is negative or greater than or equal to the number of elements remaining in iterator

getLast

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

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

forArray

public static <T> UnmodifiableIterator<T> forArray(T... array)
Returns an iterator containing the elements of array in order. The returned iterator is a view of the array; subsequent changes to the array will be reflected in the iterator.

Note: It is often preferable to represent your data using a collection type, for example using Arrays.asList(Object[]), making this method unnecessary.

The Iterable equivalent of this method is either Arrays.asList(Object[]) or ImmutableList.of(Object[])}.


singletonIterator

public static <T> UnmodifiableIterator<T> singletonIterator(@Nullable
                                                            T value)
Returns an iterator containing only value.

The Iterable equivalent of this method is Collections.singleton(T).


forEnumeration

public static <T> UnmodifiableIterator<T> forEnumeration(Enumeration<T> enumeration)
Adapts an Enumeration to the Iterator interface.

This method has no equivalent in Iterables because viewing an Enumeration as an Iterable is impossible. However, the contents can be copied into a collection using Collections.list(java.util.Enumeration).


asEnumeration

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

The Iterable equivalent of this method is either Collections.enumeration(java.util.Collection) (if you have a Collection), or Iterators.asEnumeration(collection.iterator()).


peekingIterator

public static <T> PeekingIterator<T> peekingIterator(Iterator<? extends T> iterator)
Returns a PeekingIterator backed by the given iterator.

Calls to the peek method with no intervening calls to next do not affect the iteration, and hence return the same object each time. A subsequent call to next is guaranteed to return the same object again. For example:

   PeekingIterator<String> peekingIterator =
       Iterators.peekingIterator(Iterators.forArray("a", "b"));
   String a1 = peekingIterator.peek(); // returns "a"
   String a2 = peekingIterator.peek(); // also returns "a"
   String a3 = peekingIterator.next(); // also returns "a"
Any structural changes to the underlying iteration (aside from those performed by the iterator's own PeekingIterator.remove() method) will leave the iterator in an undefined state.

The returned iterator does not support removal after peeking, as explained by PeekingIterator.remove().

Note: If the given iterator is already a PeekingIterator, it might be returned to the caller, although this is neither guaranteed to occur nor required to be consistent. For example, this method might choose to pass through recognized implementations of PeekingIterator when the behavior of the implementation is known to meet the contract guaranteed by this method.

There is no Iterable equivalent to this method, so use this method to wrap each individual iterator as it is generated.

Parameters:
iterator - the backing iterator. The PeekingIterator assumes ownership of this iterator, so users should cease making direct calls to it after calling this method.
Returns:
a peeking iterator backed by that iterator. Apart from the additional PeekingIterator.peek() method, this iterator behaves exactly the same as iterator.