com.google.common.collect
Class Iterables

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

public final class Iterables
extends java.lang.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(java.util.Collection<T> collection, java.lang.Iterable<? extends T> iterable) Adds all elements in iterable to collection.
static <T> boolean	all(java.lang.Iterable<T> iterable, Predicate<? super T> predicate) Returns true if every element in iterable satisfies the predicate.
static <T> boolean	any(java.lang.Iterable<T> iterable, Predicate<? super T> predicate) Returns true if one or more elements in iterable satisfy the predicate.
static <T> java.lang.Iterable<T>	concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> inputs) Combines multiple iterables into a single iterable.
static <T> java.lang.Iterable<T>	concat(java.lang.Iterable<? extends T>... inputs) Combines multiple iterables into a single iterable.
static <T> java.lang.Iterable<T>	concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b) Combines two iterables into a single iterable.
static boolean	contains(java.lang.Iterable<?> iterable, java.lang.Object element) Returns true if iterable contains element; that is, any object for while equals(element) is true.
static boolean	containsNull(java.lang.Iterable<?> iterable) Returns true if iterable contains at least one null element.
static <T> java.lang.Iterable<T>	cycle(java.lang.Iterable<T> iterable) Returns an iterable whose iterator cycles indefinitely over the elements of iterable.
static <T> java.lang.Iterable<T>	cycle(T... elements) Returns an iterable whose iterator cycles indefinitely over the provided elements.
static boolean	elementsEqual(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2) Determines whether two iterables contain equal elements in the same order.
static <T> java.lang.Iterable<T>	emptyIterable() Returns the empty Iterable.
static <T> java.lang.Iterable<T>	filter(java.lang.Iterable<?> unfiltered, java.lang.Class<T> type) Returns all instances of class type in unfiltered.
static <T> java.lang.Iterable<T>	filter(java.lang.Iterable<T> unfiltered, Predicate<? super T> predicate) Returns the elements of unfiltered that satisfy a predicate.
static <E> E	find(java.lang.Iterable<E> iterable, Predicate<? super E> predicate) Returns the first element in iterable that satisfies the given predicate.
static int	frequency(java.lang.Iterable<?> iterable, java.lang.Object element) Returns the number of elements in the specified iterable that equal the specified object.
static <T> T	get(java.lang.Iterable<T> iterable, int position) Returns the element at the specified position in an iterable.
static <T> T	getLast(java.lang.Iterable<T> iterable) Returns the last element of iterable.
static <T> T	getOnlyElement(java.lang.Iterable<T> iterable) Returns the single element contained in iterable.
static <T> T	getOnlyElement(java.lang.Iterable<T> iterable, T defaultValue) Returns the single element contained in iterable, or defaultValue if the iterable is empty.
static <T> boolean	isEmpty(java.lang.Iterable<T> iterable) Returns whether the given iterable contains no elements.
static <T> java.lang.Iterable<T>	limit(java.lang.Iterable<T> iterable, int limitSize) Creates an iterable with the first limitSize elements of the given iterable.
static <T> T[]	newArray(java.lang.Iterable<T> iterable, java.lang.Class<T> type) Copies an iterable's elements into an array.
static <T> java.lang.Iterable<java.lang.Iterable<T>>	partition(java.lang.Iterable<? extends T> iterable, int partitionSize, boolean padToSize) Partition an iterable into sub-iterables of the given size.
static boolean	removeAll(java.lang.Iterable<?> iterable, java.util.Collection<?> c) Removes, from an iterable, every element that belongs to the provided collection.
static boolean	retainAll(java.lang.Iterable<?> iterable, java.util.Collection<?> c) Removes, from an iterable, every element that does not belong to the provided collection.
static <T> java.lang.Iterable<T>	reverse(java.util.List<T> list) Adapts a list to an iterable with reversed iteration order.
static <T> java.lang.Iterable<T>	rotate(java.util.List<T> list, int distance) Provides a rotated view of a list.
static int	size(java.lang.Iterable<?> iterable) Returns the number of elements in iterable.
static <T> java.lang.Iterable<T>	skip(java.lang.Iterable<T> iterable, int numberToSkip) Returns a view of iterable that skips its first numberToSkip elements.
static java.lang.String	toString(java.lang.Iterable<?> iterable) Returns a string representation of iterable, with the format [e1, e2, ..., en].
static <F,T> java.lang.Iterable<T>	transform(java.lang.Iterable<F> fromIterable, Function<? super F,? extends T> function) Returns an iterable that applies function to each element of fromIterable.
static <T> java.lang.Iterable<T>	unmodifiableIterable(java.lang.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> java.lang.Iterable<T> emptyIterable()

Returns the empty Iterable.

unmodifiableIterable

public static <T> java.lang.Iterable<T> unmodifiableIterable(java.lang.Iterable<T> iterable)

Returns an unmodifiable view of iterable.

size

public static int size(java.lang.Iterable<?> iterable)

Returns the number of elements in iterable.

contains

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

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

containsNull

public static boolean containsNull(java.lang.Iterable<?> iterable)

Returns true if iterable contains at least one null element.

removeAll

public static boolean removeAll(java.lang.Iterable<?> iterable,
                                java.util.Collection<?> c)

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:

iterable - the iterable to (potentially) remove elements from

c - the elements to remove

Returns:

true if any elements are removed from iterable

retainAll

public static boolean retainAll(java.lang.Iterable<?> iterable,
                                java.util.Collection<?> c)

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:

iterable - the iterable to (potentially) remove elements from

c - the elements to retain

Returns:

true if any elements are removed from iterable

elementsEqual

public static boolean elementsEqual(java.lang.Iterable<?> iterable1,
                                    java.lang.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 java.lang.String toString(java.lang.Iterable<?> iterable)

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

getOnlyElement

public static <T> T getOnlyElement(java.lang.Iterable<T> iterable)

Returns the single element contained in iterable.

Throws:

java.util.NoSuchElementException - if the iterable is empty

java.lang.IllegalArgumentException - if the iterable contains multiple elements

getOnlyElement

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

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

Throws:

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

newArray

public static <T> T[] newArray(java.lang.Iterable<T> iterable,
                               java.lang.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(java.util.Collection<T> collection,
                                 java.lang.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(java.lang.Iterable<?> iterable,
                            @Nullable
                            java.lang.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> java.lang.Iterable<T> cycle(java.lang.Iterable<T> iterable)

Returns an iterable whose iterator cycles 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> java.lang.Iterable<T> cycle(T... elements)

Returns an iterable whose iterator cycles indefinitely over the provided elements.

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

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

concat

public static <T> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> a,
                                               java.lang.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> java.lang.Iterable<T> concat(java.lang.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:

java.lang.NullPointerException - if any of the provided iterables is null

concat

public static <T> java.lang.Iterable<T> concat(java.lang.Iterable<? extends java.lang.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> java.lang.Iterable<java.lang.Iterable<T>> partition(java.lang.Iterable<? extends T> iterable,
                                                                      int partitionSize,
                                                                      boolean padToSize)

Partition an iterable into sub-iterables of the given size. For example, {A, B, C, D, E, F} with partition size 3 yields {A, B, C} and {D, E, F}. The returned iterables have iterators that do not support remove().

After next() is called on the returned iterable's iterator, the iterables from prior next() calls become invalid.

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 across partitioned iterables

filter

public static <T> java.lang.Iterable<T> filter(java.lang.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> java.lang.Iterable<T> filter(java.lang.Iterable<?> unfiltered,
                                               java.lang.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(java.lang.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(java.lang.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 <E> E find(java.lang.Iterable<E> iterable,
                         Predicate<? super E> predicate)

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

Throws:

java.util.NoSuchElementException - if no element in iterable matches the given predicate

transform

public static <F,T> java.lang.Iterable<T> transform(java.lang.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(java.lang.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:

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

getLast

public static <T> T getLast(java.lang.Iterable<T> iterable)

Returns the last element of iterable.

Returns:

the last element of iterable

Throws:

java.util.NoSuchElementException - if the iterable has no elements

skip

public static <T> java.lang.Iterable<T> skip(java.lang.Iterable<T> iterable,
                                             int numberToSkip)

Returns a view of iterable that skips its first numberToSkip elements. If iterable contains fewer than numberToSkip elements, the returned iterable skips all of its elements.

Modifications to the underlying Iterable before a call to iterator() are reflected in the returned iterator. That is, the iterator skips the first numberToSkip elements that exist when the Iterator is created, not when skip() is called.

The returned iterable's iterator supports remove() if the iterator of the underlying iterable supports it. Note that it is not possible to delete the last skipped element by immediately calling remove() on that iterator, as the Iterator contract states that a call to remove() before a call to next() will throw an IllegalStateException.

limit

public static <T> java.lang.Iterable<T> limit(java.lang.Iterable<T> iterable,
                                              int limitSize)

Creates an iterable with the first limitSize elements of the given iterable. If the original iterable does not contain that many elements, the returned iterator will have the same behavior as the original iterable. The returned iterable's iterator supports remove() if the original iterator does.

Parameters:

iterable - the iterable to limit

limitSize - the maximum number of elements in the returned iterator

Throws:

java.lang.IllegalArgumentException - if limitSize is negative

reverse

public static <T> java.lang.Iterable<T> reverse(java.util.List<T> list)

Adapts a list to an iterable with reversed iteration order. It is 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> java.lang.Iterable<T> rotate(java.util.List<T> list,
                                               int distance)

Provides a rotated view of a list. Differs from Collections.rotate(java.util.List, int) 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 retrieved from a rotated view of the list is undefined if the list is structurally changed after the iterator is retrieved.

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

isEmpty

public static <T> boolean isEmpty(java.lang.Iterable<T> iterable)

Returns whether the given iterable contains no elements.

Returns:

true if the iterable has no elements, false if the iterable has one or more elements