com.google.common.collect
Class Iterables

java.lang.Object
  extended by 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 no element in iterable evaluates to false under predicate.
static
<T> boolean
any(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)
          Returns true if some element in iterable evaluates to true under predicate.
static
<T> java.lang.Iterable<T>
concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables)
          Variant of Iterators.concat that acts on and returns instances of Iterable.
static
<T> java.lang.Iterable<T>
concat(java.lang.Iterable<? extends T>... iterables)
          Variant of Iterators.concat that acts on and returns instances of Iterable.
static
<T> java.lang.Iterable<T>
concat(java.lang.Iterable<? extends T> firstElements, java.lang.Iterable<? extends T> nextElements)
          Variant of Iterators.concat that acts on and returns instances of Iterable.
static
<T> java.lang.Iterable<T>
cycle(java.lang.Iterable<T> iterable)
          Variant of Iterators.cycle which returns an Iterable.
static
<T> java.lang.Iterable<T>
cycle(T... elements)
          Variant of cycle(Iterable) accepting varargs parameters.
static boolean elementsEqual(java.lang.Iterable<?> iterable1, java.lang.Iterable<?> iterable2)
          Determines whether the two Iterables contain equal elements.
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 type found in unfiltered.
static
<T> java.lang.Iterable<T>
filter(java.lang.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(java.lang.Iterable<E> iterable, Predicate<? super E> predicate)
          Returns the first element in iterable for which the given predicate matches.
static int frequency(java.lang.Iterable<?> iterable, java.lang.Object element)
          Variant of Collections.frequency for iterables.
static
<T> T
getLast(java.lang.Iterable<T> iterable)
          Returns the last element of iterable, or throws a NoSuchElementException if it has no elements.
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 iterator, or defaultValue if the iterator 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 limit)
          Variant of Iterators.limit(Iterator,int), which accepts and returns an iterable instead of an iterator.
static
<T> T[]
newArray(java.lang.Iterable<T> iterable, java.lang.Class<T> type)
          Converts an Iterable 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 like so: {A, B, C, D, E, F} with partition size 3 => {A, B, C} and {D, E, F}.
static
<T> java.lang.Iterable<T>
reverse(java.util.List<T> list)
          Adapt a list to an Iterable over a reversed version of the list.
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 present in iterable.
static
<T> java.lang.Iterable<T>
skip(java.lang.Iterable<T> iterable, int numberToSkip)
          Returns a view of iterable whose Iterator skips its first numberToSkip elements or, if iterable contains fewer than numberToSkip elements, skips all its elements.
static java.lang.String toString(java.lang.Iterable<?> iterable)
          Returns a string representation of iterable in the same format as Iterators#toString(java.util.Iterator).
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 present in iterable.


elementsEqual

public static boolean elementsEqual(java.lang.Iterable<?> iterable1,
                                    java.lang.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 java.lang.String toString(java.lang.Iterable<?> iterable)
Returns a string representation of iterable in the same format as Iterators#toString(java.util.Iterator).


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 iterator, or defaultValue if the iterator 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)
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(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)
Variant of Collections.frequency for iterables.


cycle

public static <T> java.lang.Iterable<T> cycle(java.lang.Iterable<T> iterable)
Variant of Iterators.cycle which returns an Iterable.

See Also:
Iterators.cycle(Iterable)

cycle

public static <T> java.lang.Iterable<T> cycle(T... elements)
Variant of cycle(Iterable) accepting varargs parameters.


concat

public static <T> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> firstElements,
                                               java.lang.Iterable<? extends T> nextElements)
Variant of Iterators.concat that acts on and returns instances of Iterable.


concat

public static <T> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T>... iterables)
Variant of Iterators.concat that acts on and returns instances of Iterable.


concat

public static <T> java.lang.Iterable<T> concat(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables)
Variant of Iterators.concat that acts on and returns instances of Iterable.


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 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> java.lang.Iterable<T> filter(java.lang.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> java.lang.Iterable<T> filter(java.lang.Iterable<?> unfiltered,
                                               java.lang.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(java.lang.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(java.lang.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(java.lang.Iterable<E> iterable,
                         Predicate<? super E> predicate)
Returns the first element in iterable for which the given predicate matches.

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.


reverse

public static <T> java.lang.Iterable<T> reverse(java.util.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> 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) 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

limit

public static <T> java.lang.Iterable<T> limit(java.lang.Iterable<T> iterable,
                                              int limit)
Variant of Iterators.limit(Iterator,int), which accepts and returns an iterable instead of an iterator.

See Also:
Iterators.limit(Iterator, int)

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

skip

public static <T> java.lang.Iterable<T> skip(java.lang.Iterable<T> iterable,
                                             int numberToSkip)
Returns a view of iterable whose Iterator skips its first numberToSkip elements or, if iterable contains fewer than numberToSkip elements, skips all its elements.

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

Structural modifications to the underlying Iterable after a call to iterator() may result in undefined behavior by the returned Iterator, depending upon the concurrent-modification policy of the underlying Iterable. Non-structural changes to the underlying Iterable are always reflected in the returned Iterable.

Iterator.remove() is supported if iterators of the underlying Iterable supports it. (Note that it is not possible to delete the last skipped element by immediately calling remove() on a new iterator, as the Iterator contract requires that a call to remove() before a call to next() will throw an IllegalStateException.)


getLast

public static <T> T getLast(java.lang.Iterable<T> iterable)
Returns the last element of iterable, or throws a NoSuchElementException if it has no elements.



Copyright © 2008 Google. All Rights Reserved.