Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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 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> 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 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`

### 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

### 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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD