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. Also see the parallel implementations in Iterators.

Author:

Kevin Bourrillion, Scott Bonneau

Method Summary

static <T> boolean	addAll(Collection<T> collection, Iterable<? extends T> iterable) Adds all elements in iterable to collection.
static <T> boolean	all(Iterable<T> iterable, Predicate<? super T> predicate) Returns true if no element in iterable evaluates to false under predicate.
static <T> boolean	any(Iterable<T> iterable, Predicate<? super T> predicate) Returns true if some element in iterable evaluates to true under predicate.
static <T> Iterable<T>	concat(Iterable<? extends Iterable<? extends T>> iterables) Variant of Iterators.concat that acts on and returns instances of Iterable.
static <T> Iterable<T>	concat(Iterable<? extends T>... iterables) Variant of Iterators.concat that acts on and returns instances of Iterable.
static <T> Iterable<T>	concat(Iterable<? extends T> firstElements, Iterable<? extends T> nextElements) Variant of Iterators.concat that acts on and returns instances of Iterable.
static <T> Iterable<T>	cycle(Iterable<T> iterable) Variant of Iterators.cycle which returns an Iterable.
static <T> Iterable<T>	cycle(T... elements) Variant of cycle(Iterable) accepting varargs parameters.
static boolean	elementsEqual(Iterable<?> iterable1, Iterable<?> iterable2) Determines whether the two Iterables contain equal elements.
static <T> Iterable<T>	emptyIterable() Returns the empty Iterable.
static <T> Iterable<T>	filter(Iterable<?> unfiltered, Class<T> type) Returns all instances of type found in unfiltered.
static <T> Iterable<T>	filter(Iterable<T> unfiltered, Predicate<? super T> predicate) Variant of Iterators.filter(Iterator,Predicate), which accepts and returns an iterable instead of an iterator.
static <E> E	find(Iterable<E> iterable, Predicate<? super E> predicate) Returns the first element in iterable for which the given predicate matches.
static int	frequency(Iterable<?> iterable, Object element) Variant of Collections.frequency for iterables.
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 iterator, or defaultValue if the iterator is empty.
static <T> T[]	newArray(Iterable<T> iterable, Class<T> type) Converts an Iterable into an array.
static <T> Iterable<Iterable<T>>	partition(Iterable<? extends T> iterable, int partitionSize, boolean padToSize) Partition an iterable into sub iterables 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> Iterable<T>	reverse(List<T> list) Adapt a list to an Iterable over a reversed version of the list.
static <T> Iterable<T>	rotate(List<T> list, int distance) Provides a rotated view of a list.
static String	toString(Iterable<?> iterable) Returns a string representation of iterable in the same format as Iterators#toString(java.util.Iterator).
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

emptyIterable

public static <T> Iterable<T> emptyIterable()

Returns the empty Iterable.

unmodifiableIterable

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

Returns an unmodifiable view of iterable.

elementsEqual

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

Determines whether the two Iterables contain equal elements. 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 in the same format as Iterators#toString(java.util.Iterator).

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 iterator, or defaultValue if the iterator is empty.

Throws:

IllegalArgumentException - if the iterator contains multiple elements

newArray

public static <T> T[] newArray(Iterable<T> iterable,
                               Class<T> type)

Converts an Iterable into an array.

Parameters:

iterable - any instance of Iterable (will not be modified)

type - the type of the elements

Returns:

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

addAll

public static <T> boolean addAll(Collection<T> collection,
                                 Iterable<? extends T> iterable)

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)

Variant of Collections.frequency for iterables.

cycle

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

Variant of Iterators.cycle which returns an Iterable.

See Also:

Iterators.cycle(Iterable)

cycle

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

Variant of cycle(Iterable) accepting varargs parameters.

concat

public static <T> Iterable<T> concat(Iterable<? extends T> firstElements,
                                     Iterable<? extends T> nextElements)

Variant of Iterators.concat that acts on and returns instances of Iterable.

concat

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

Variant of Iterators.concat that acts on and returns instances of Iterable.

concat

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

Variant of Iterators.concat that acts on and returns instances of Iterable.

partition

public static <T> Iterable<Iterable<T>> partition(Iterable<? extends T> iterable,
                                                  int partitionSize,
                                                  boolean padToSize)

Partition an iterable into sub iterables 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 iterable Once you read forward any iterables from previous partitions will become invalid.

NOTE: This is optimized for a the simple case of iterating through each sub-iterable in order only once. Other operations will succeed, but will suffer a performance penalty to maintain correctness.

Parameters:

iterable - the iterable to partition

partitionSize - the size of each partition

padToSize - whether to pad the last partition to the partition size with null.

Returns:

an iterable of partitioned iterables

filter

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

Variant of Iterators.filter(Iterator,Predicate), which accepts and returns an iterable instead of an iterator.

See Also:

Iterators.filter(Iterator, Predicate)

filter

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

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

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 some element in iterable evaluates to true under predicate. Returns false if iterable is empty.

all

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

Returns true if no element in iterable evaluates to false under predicate. Returns true if iterable is empty.

find

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

Returns the first element in iterable for which the given predicate matches.

Throws:

NoSuchElementException - if no element in iterable matches the given predicate

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.

reverse

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

Adapt a list to an Iterable over a reversed version of the list. Requires a List so that we can reverse it with no copying required. Especially useful in foreach-style loops:

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

Returns:

an Iterable with the same elements as the list, in reverse.

rotate

public static <T> Iterable<T> rotate(List<T> list,
                                     int distance)

Provides a rotated view of a list. Differs from Collections.rotate(java.util.List, int) only in that it leaves the underlying list unchanged. Note that this is a "live" view of the list that will change as the list changes. However, the behavior of an Iterator constructed from a rotated view of the list is undefined if the list is changed after the Iterator is constructed.

Parameters:

list - the list to return a rotated view of.

distance - the distance to rotate the list. There are no constraints on this value; it may be zero, negative, or greater than list.size().

Returns:

a rotated view of the given list