com.google.common.collect
Class Iterables

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

public final class Iterables
extends Object

This class contains static utility methods that operate on or return objects of type Iterable. Except as noted, each method has a corresponding Iterator-based method in the Iterators class.

Since:

2010.01.04 stable (imported from Google Collections Library)

Author:

Kevin Bourrillion, Jared Levy

Method Summary

static <T> boolean	addAll(Collection<T> addTo, Iterable<? extends T> elementsToAdd) Adds all elements in iterable to collection.
static <T> boolean	all(Iterable<T> iterable, Predicate<? super T> predicate) Returns true if every element in iterable satisfies the predicate.
static <T> boolean	any(Iterable<T> iterable, Predicate<? super T> predicate) Returns true if one or more elements in iterable satisfy the predicate.
static <T> Iterable<T>	concat(Iterable<? extends Iterable<? extends T>> inputs) Combines multiple iterables into a single iterable.
static <T> Iterable<T>	concat(Iterable<? extends T>... inputs) Combines multiple iterables into a single iterable.
static <T> Iterable<T>	concat(Iterable<? extends T> a, Iterable<? extends T> b) Combines two iterables into a single iterable.
static <T> Iterable<T>	concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c) Combines three iterables into a single iterable.
static <T> Iterable<T>	concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c, Iterable<? extends T> d) Combines four iterables into a single iterable.
static <T> Iterable<T>	consumingIterable(Iterable<T> iterable) Returns a view of the supplied iterable that wraps each generated Iterator through Iterators.consumingIterator(Iterator).
static boolean	contains(Iterable<?> iterable, Object element) Returns true if iterable contains element; that is, any object for while equals(element) is true.
static <T> Iterable<T>	cycle(Iterable<T> iterable) Returns an iterable whose iterators cycle indefinitely over the elements of iterable.
static <T> Iterable<T>	cycle(T... elements) Returns an iterable whose iterators cycle indefinitely over the provided elements.
static boolean	elementsEqual(Iterable<?> iterable1, Iterable<?> iterable2) Determines whether two iterables contain equal elements in the same order.
static <T> Iterable<T>	filter(Iterable<?> unfiltered, Class<T> type) Returns all instances of class type in unfiltered.
static <T> Iterable<T>	filter(Iterable<T> unfiltered, Predicate<? super T> predicate) Returns the elements of unfiltered that satisfy a predicate.
static <T> T	find(Iterable<T> iterable, Predicate<? super T> predicate) Returns the first element in iterable that satisfies the given predicate.
static int	frequency(Iterable<?> iterable, Object element) Returns the number of elements in the specified iterable that equal the specified object.
static <T> T	get(Iterable<T> iterable, int position) Returns the element at the specified position in an iterable.
static <T> T	getLast(Iterable<T> iterable) Returns the last element of iterable.
static <T> T	getOnlyElement(Iterable<T> iterable) Returns the single element contained in iterable.
static <T> T	getOnlyElement(Iterable<T> iterable, T defaultValue) Returns the single element contained in iterable, or defaultValue if the iterable is empty.
static <T> int	indexOf(Iterable<T> iterable, Predicate<? super T> predicate) Returns the index in iterable of the first element that satisfies the provided predicate, or -1 if the Iterable has no such elements.
static <T> boolean	isEmpty(Iterable<T> iterable) Determines if the given iterable contains no elements.
static <T> Iterable<List<T>>	paddedPartition(Iterable<T> iterable, int size) Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary.
static <T> Iterable<List<T>>	partition(Iterable<T> iterable, int size) Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).
static boolean	removeAll(Iterable<?> removeFrom, Collection<?> elementsToRemove) Removes, from an iterable, every element that belongs to the provided collection.
static <T> boolean	removeIf(Iterable<T> removeFrom, Predicate<? super T> predicate) Removes, from an iterable, every element that satisfies the provided predicate.
static boolean	retainAll(Iterable<?> removeFrom, Collection<?> elementsToRetain) Removes, from an iterable, every element that does not belong to the provided collection.
static <T> Iterable<T>	reverse(List<T> list) Adapts a list to an iterable with reversed iteration order.
static int	size(Iterable<?> iterable) Returns the number of elements in iterable.
static <T> T[]	toArray(Iterable<? extends T> iterable, Class<T> type) Copies an iterable's elements into an array.
static String	toString(Iterable<?> iterable) Returns a string representation of iterable, with the format [e1, e2, ..., en].
static <F,T> Iterable<T>	transform(Iterable<F> fromIterable, Function<? super F,? extends T> function) Returns an iterable that applies function to each element of fromIterable.
static <T> Iterable<T>	unmodifiableIterable(Iterable<T> iterable) Returns an unmodifiable view of iterable.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

unmodifiableIterable

public static <T> Iterable<T> unmodifiableIterable(Iterable<T> iterable)

Returns an unmodifiable view of iterable.

size

public static int size(Iterable<?> iterable)

Returns the number of elements in iterable.

contains

public static boolean contains(Iterable<?> iterable,
                               @Nullable
                               Object element)

Returns true if iterable contains element; that is, any object for while equals(element) is true.

removeAll

public static boolean removeAll(Iterable<?> removeFrom,
                                Collection<?> elementsToRemove)

Removes, from an iterable, every element that belongs to the provided collection.

This method calls Collection.removeAll(java.util.Collection) if iterable is a collection, and Iterators.removeAll(java.util.Iterator, java.util.Collection) otherwise.

Parameters:

removeFrom - the iterable to (potentially) remove elements from

elementsToRemove - the elements to remove

Returns:

true if any elements are removed from iterable

retainAll

public static boolean retainAll(Iterable<?> removeFrom,
                                Collection<?> elementsToRetain)

Removes, from an iterable, every element that does not belong to the provided collection.

This method calls Collection.retainAll(java.util.Collection) if iterable is a collection, and Iterators.retainAll(java.util.Iterator, java.util.Collection) otherwise.

Parameters:

removeFrom - the iterable to (potentially) remove elements from

elementsToRetain - the elements to retain

Returns:

true if any elements are removed from iterable

removeIf

public static <T> boolean removeIf(Iterable<T> removeFrom,
                                   Predicate<? super T> predicate)

Removes, from an iterable, every element that satisfies the provided predicate.

Parameters:

removeFrom - the iterable to (potentially) remove elements from

predicate - a predicate that determines whether an element should be removed

Returns:

true if any elements were removed from the iterable

Throws:

UnsupportedOperationException - if the iterable does not support remove().

Since:

2010.01.04 tentative

elementsEqual

public static boolean elementsEqual(Iterable<?> iterable1,
                                    Iterable<?> iterable2)

Determines whether two iterables contain equal elements in the same order. More specifically, this method returns true if iterable1 and iterable2 contain the same number of elements and every element of iterable1 is equal to the corresponding element of iterable2.

toString

public static String toString(Iterable<?> iterable)

Returns a string representation of iterable, with the format [e1, e2, ..., en].

getOnlyElement

public static <T> T getOnlyElement(Iterable<T> iterable)

Returns the single element contained in iterable.

Throws:

NoSuchElementException - if the iterable is empty

IllegalArgumentException - if the iterable contains multiple elements

getOnlyElement

public static <T> T getOnlyElement(Iterable<T> iterable,
                                   @Nullable
                                   T defaultValue)

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

Throws:

IllegalArgumentException - if the iterator contains multiple elements

toArray

public static <T> T[] toArray(Iterable<? extends T> iterable,
                              Class<T> type)

Copies an iterable's elements into an array.

Parameters:

iterable - the iterable to copy

type - the type of the elements

Returns:

a newly-allocated array into which all the elements of the iterable have been copied

addAll

public static <T> boolean addAll(Collection<T> addTo,
                                 Iterable<? extends T> elementsToAdd)

Adds all elements in iterable to collection.

Returns:

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

frequency

public static int frequency(Iterable<?> iterable,
                            @Nullable
                            Object element)

Returns the number of elements in the specified iterable that equal the specified object.

See Also:

Collections.frequency(java.util.Collection, java.lang.Object)

cycle

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

Returns an iterable whose iterators cycle indefinitely over the elements of iterable.

That iterator supports remove() if iterable.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.

To cycle over the iterable n times, use the following: Iterables.concat(Collections.nCopies(n, iterable))

cycle

public static <T> Iterable<T> cycle(T... elements)

Returns an iterable whose iterators cycle indefinitely over the provided elements.

After remove is invoked on a generated iterator, the removed element will no longer appear in either that iterator or any other iterator created from the same source iterable. That is, this method behaves exactly as Iterables.cycle(Lists.newArrayList(elements)). 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.

To cycle over the elements n times, use the following: Iterables.concat(Collections.nCopies(n, Arrays.asList(elements)))

concat

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

Combines two iterables into a single iterable. The returned iterable has an iterator that traverses the elements in a, followed by the elements in b. The source iterators are not polled until necessary.

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

concat

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

Combines three iterables into a single iterable. The returned iterable has an iterator that traverses 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 iterable's iterator supports remove() when the corresponding input iterator supports it.

concat

public static <T> Iterable<T> concat(Iterable<? extends T> a,
                                     Iterable<? extends T> b,
                                     Iterable<? extends T> c,
                                     Iterable<? extends T> d)

Combines four iterables into a single iterable. The returned iterable has an iterator that traverses 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 iterable's iterator supports remove() when the corresponding input iterator supports it.

concat

public static <T> Iterable<T> concat(Iterable<? extends T>... inputs)

Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable in inputs. The input iterators are not polled until necessary.

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

Throws:

NullPointerException - if any of the provided iterables is null

concat

public static <T> Iterable<T> concat(Iterable<? extends Iterable<? extends T>> inputs)

Combines multiple iterables into a single iterable. The returned iterable has an iterator that traverses the elements of each iterable in inputs. The input iterators are not polled until necessary.

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

partition

public static <T> Iterable<List<T>> partition(Iterable<T> iterable,
                                              int size)

Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller). For example, partitioning an iterable containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e]] -- an outer iterable containing two inner lists of three and two elements, all in the original order.

Iterators returned by the returned iterable do not support the Iterator.remove() method. The returned lists implement RandomAccess, whether or not the input list does.

Note: if iterable is a List, use Lists.partition(List, int) instead.

Parameters:

iterable - the iterable to return a partitioned view of

size - the desired size of each partition (the last may be smaller)

Returns:

an iterable of unmodifiable lists containing the elements of iterable divided into partitions

Throws:

IllegalArgumentException - if size is nonpositive

paddedPartition

public static <T> Iterable<List<T>> paddedPartition(Iterable<T> iterable,
                                                    int size)

Divides an iterable into unmodifiable sublists of the given size, padding the final iterable with null values if necessary. For example, partitioning an iterable containing [a, b, c, d, e] with a partition size of 3 yields [[a, b, c], [d, e, null]] -- an outer iterable containing two inner lists of three elements each, all in the original order.

Iterators returned by the returned iterable do not support the Iterator.remove() method.

Parameters:

iterable - the iterable to return a partitioned view of

size - the desired size of each partition

Returns:

an iterable of unmodifiable lists containing the elements of iterable divided into partitions (the final iterable may have trailing null elements)

Throws:

IllegalArgumentException - if size is nonpositive

filter

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

Returns the elements of unfiltered that satisfy a predicate. The resulting iterable's iterator does not support remove().

filter

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

Returns all instances of class type in unfiltered. The returned iterable has elements whose class is type or a subclass of type. The returned iterable's iterator does not support remove().

Parameters:

unfiltered - an iterable containing objects of any type

type - the type of elements desired

Returns:

an unmodifiable iterable containing all elements of the original iterable that were of the requested type

any

public static <T> boolean any(Iterable<T> iterable,
                              Predicate<? super T> predicate)

Returns true if one or more elements in iterable satisfy the predicate.

all

public static <T> boolean all(Iterable<T> iterable,
                              Predicate<? super T> predicate)

Returns true if every element in iterable satisfies the predicate. If iterable is empty, true is returned.

find

public static <T> T find(Iterable<T> iterable,
                         Predicate<? super T> predicate)

Returns the first element in iterable that satisfies the given predicate.

Throws:

NoSuchElementException - if no element in iterable matches the given predicate

indexOf

public static <T> int indexOf(Iterable<T> iterable,
                              Predicate<? super T> predicate)

Returns the index in iterable of the first element that satisfies the provided predicate, or -1 if the Iterable has no such elements.

More formally, returns the lowest index i such that predicate.apply(Iterables.get(iterable, i)) is true or -1 if there is no such index.

Since:

2010.01.04 tentative

transform

public static <F,T> Iterable<T> transform(Iterable<F> fromIterable,
                                          Function<? super F,? extends T> function)

Returns an iterable that applies function to each element of fromIterable.

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

get

public static <T> T get(Iterable<T> iterable,
                        int position)

Returns the element at the specified position in an iterable.

Parameters:

position - position of the element to return

Returns:

the element at the specified position in iterable

Throws:

IndexOutOfBoundsException - if position is negative or greater than or equal to the size of iterable

getLast

public static <T> T getLast(Iterable<T> iterable)

Returns the last element of iterable.

Returns:

the last element of iterable

Throws:

NoSuchElementException - if the iterable has no elements

consumingIterable

public static <T> Iterable<T> consumingIterable(Iterable<T> iterable)

Returns a view of the supplied iterable that wraps each generated Iterator through Iterators.consumingIterator(Iterator).

Parameters:

iterable - the iterable to wrap

Returns:

a view of the supplied iterable that wraps each generated iterator through Iterators.consumingIterator(Iterator)

Since:

2010.01.04 tentative

See Also:

Iterators.consumingIterator(Iterator)

reverse

public static <T> Iterable<T> reverse(List<T> list)

Adapts a list to an iterable with reversed iteration order. It is especially useful in foreach-style loops:

   List<String> mylist = ...
   for (String str : Iterables.reverse(mylist)) {
     ...
   }

There is no corresponding method in Iterators, since Iterable.iterator() can simply be invoked on the result of calling this method.

Returns:

an iterable with the same elements as the list, in reverse

isEmpty

public static <T> boolean isEmpty(Iterable<T> iterable)

Determines if the given iterable contains no elements.

There is no precise Iterator equivalent to this method, since one can only ask an iterator whether it has any elements remaining (which one does using Iterator.hasNext()).

Returns:

true if the iterable contains no elements