@GwtCompatible(emulated=true) public final class Iterables extends Object
Iterable. Except as noted, each method has a corresponding
 Iterator-based method in the Iterators class.
 Performance notes: Unless otherwise noted, all of the iterables produced in this class are lazy, which means that their iterators only advance the backing iteration when absolutely necessary.
See the Guava User Guide article on 
 Iterables.
| Modifier and Type | Method and Description | 
|---|---|
| static <T> boolean | addAll(Collection<T> addTo,
            Iterable<? extends T> elementsToAdd)Adds all elements in  iterabletocollection. | 
| static <T> boolean | all(Iterable<T> iterable,
      Predicate<? super T> predicate)Returns  trueif every element initerablesatisfies the
 predicate. | 
| static <T> boolean | any(Iterable<T> iterable,
      Predicate<? super T> predicate)Returns  trueif any element initerablesatisfies 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
  IteratorthroughIterators.consumingIterator(Iterator). | 
| static boolean | contains(Iterable<?> iterable,
                Object element)Returns  trueifiterablecontains any object for whichequals(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  typeinunfiltered. | 
| static <T> Iterable<T> | filter(Iterable<T> unfiltered,
            Predicate<? super T> predicate)Returns the elements of  unfilteredthat satisfy a predicate. | 
| static <T> T | find(Iterable<? extends T> iterable,
        Predicate<? super T> predicate,
        T defaultValue)Returns the first element in  iterablethat satisfies the given
 predicate, ordefaultValueif none found. | 
| static <T> T | find(Iterable<T> iterable,
        Predicate<? super T> predicate)Returns the first element in  iterablethat satisfies the given
 predicate; use this method only when such an element is known to exist. | 
| 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<? extends T> iterable,
      int position,
      T defaultValue)Returns the element at the specified position in an iterable or a default
 value otherwise. | 
| static <T> T | get(Iterable<T> iterable,
      int position)Returns the element at the specified position in an iterable. | 
| static <T> T | getFirst(Iterable<? extends T> iterable,
                T defaultValue)Returns the first element in  iterableordefaultValueif
 the iterable is empty. | 
| static <T> T | getLast(Iterable<? extends T> iterable,
              T defaultValue)Returns the last element of  iterableordefaultValueif
 the iterable is empty. | 
| static <T> T | getLast(Iterable<T> iterable)Returns the last element of  iterable. | 
| static <T> T | getOnlyElement(Iterable<? extends T> iterable,
                            T defaultValue)Returns the single element contained in  iterable, ordefaultValueif the iterable is empty. | 
| static <T> T | getOnlyElement(Iterable<T> iterable)Returns the single element contained in  iterable. | 
| static <T> int | indexOf(Iterable<T> iterable,
              Predicate<? super T> predicate)Returns the index in  iterableof the first element that satisfies
 the providedpredicate, or-1if the Iterable has no such
 elements. | 
| static boolean | isEmpty(Iterable<?> iterable)Determines if the given iterable contains no elements. | 
| static <T> Iterable<T> | limit(Iterable<T> iterable,
          int limitSize)Creates an iterable with the first  limitSizeelements of the given
 iterable. | 
| static <T> Iterable<T> | mergeSorted(Iterable<? extends Iterable<? extends T>> iterables,
                      Comparator<? super T> comparator)Returns an iterable over the merged contents of all given
  iterables. | 
| 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 int | size(Iterable<?> iterable)Returns the number of elements in  iterable. | 
| static <T> Iterable<T> | skip(Iterable<T> iterable,
        int numberToSkip)Returns a view of  iterablethat skips its firstnumberToSkipelements. | 
| 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](that is, identical toArrays.toString(Iterables.toArray(iterable))). | 
| static <F,T> Iterable<T> | transform(Iterable<F> fromIterable,
                  Function<? super F,? extends T> function)Returns an iterable that applies  functionto each element offromIterable. | 
| static <T> Optional<T> | tryFind(Iterable<T> iterable,
              Predicate<? super T> predicate)Returns an  Optionalcontaining the first element initerablethat satisfies the given predicate, if such an element exists. | 
| static <E> Iterable<E> | unmodifiableIterable(ImmutableCollection<E> iterable)Deprecated. 
 no need to use this | 
| static <T> Iterable<T> | unmodifiableIterable(Iterable<T> iterable)Returns an unmodifiable view of  iterable. | 
public static <T> Iterable<T> unmodifiableIterable(Iterable<T> iterable)
iterable.@Deprecated public static <E> Iterable<E> unmodifiableIterable(ImmutableCollection<E> iterable)
public static boolean contains(Iterable<?> iterable, @Nullable Object element)
true if iterable contains any object for which equals(element)
 is true.public static boolean removeAll(Iterable<?> removeFrom, Collection<?> elementsToRemove)
This method calls Collection.removeAll(java.util.Collection<?>) if iterable is a
 collection, and Iterators.removeAll(java.util.Iterator<?>, java.util.Collection<?>) otherwise.
removeFrom - the iterable to (potentially) remove elements fromelementsToRemove - the elements to removetrue if any element was removed from iterablepublic static boolean retainAll(Iterable<?> removeFrom, Collection<?> elementsToRetain)
This method calls Collection.retainAll(java.util.Collection<?>) if iterable is a
 collection, and Iterators.retainAll(java.util.Iterator<?>, java.util.Collection<?>) otherwise.
removeFrom - the iterable to (potentially) remove elements fromelementsToRetain - the elements to retaintrue if any element was removed from iterablepublic static <T> boolean removeIf(Iterable<T> removeFrom, Predicate<? super T> predicate)
removeFrom - the iterable to (potentially) remove elements frompredicate - a predicate that determines whether an element should
     be removedtrue if any elements were removed from the iterableUnsupportedOperationException - if the iterable does not support
     remove().@CheckReturnValue public static boolean elementsEqual(Iterable<?> iterable1, Iterable<?> iterable2)
true if iterable1
 and iterable2 contain the same number of elements and every element
 of iterable1 is equal to the corresponding element of
 iterable2.public static String toString(Iterable<?> iterable)
iterable, with the format [e1, e2, ..., en] (that is, identical to Arrays.toString(Iterables.toArray(iterable))). Note that for
 most implementations of Collection, collection.toString() also gives the same result, but that behavior is not
 generally guaranteed.public static <T> T getOnlyElement(Iterable<T> iterable)
iterable.NoSuchElementException - if the iterable is emptyIllegalArgumentException - if the iterable contains multiple
     elements@Nullable public static <T> T getOnlyElement(Iterable<? extends T> iterable, @Nullable T defaultValue)
iterable, or defaultValue if the iterable is empty.IllegalArgumentException - if the iterator contains multiple
     elements@GwtIncompatible(value="Array.newInstance(Class, int)") public static <T> T[] toArray(Iterable<? extends T> iterable, Class<T> type)
iterable - the iterable to copytype - the type of the elementspublic static <T> boolean addAll(Collection<T> addTo, Iterable<? extends T> elementsToAdd)
iterable to collection.true if collection was modified as a result of this
     operation.public static <T> Iterable<T> cycle(Iterable<T> iterable)
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))
public static <T> Iterable<T> cycle(T... 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)))
public static <T> Iterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b)
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.
public static <T> Iterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c)
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.
public static <T> Iterable<T> concat(Iterable<? extends T> a, Iterable<? extends T> b, Iterable<? extends T> c, Iterable<? extends T> d)
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.
public static <T> Iterable<T> concat(Iterable<? extends T>... inputs)
inputs. The input iterators are not polled until necessary.
 The returned iterable's iterator supports remove() when the
 corresponding input iterator supports it.
NullPointerException - if any of the provided iterables is nullpublic static <T> Iterable<T> concat(Iterable<? extends Iterable<? extends T>> inputs)
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 is null.
public static <T> Iterable<List<T>> partition(Iterable<T> iterable, int size)
[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.
iterable - the iterable to return a partitioned view ofsize - the desired size of each partition (the last may be smaller)iterable divided into partitionsIllegalArgumentException - if size is nonpositivepublic static <T> Iterable<List<T>> paddedPartition(Iterable<T> iterable, int size)
[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.
iterable - the iterable to return a partitioned view ofsize - the desired size of each partitioniterable divided into partitions (the final iterable may have
     trailing null elements)IllegalArgumentException - if size is nonpositive@CheckReturnValue public static <T> Iterable<T> filter(Iterable<T> unfiltered, Predicate<? super T> predicate)
unfiltered that satisfy a predicate. The
 resulting iterable's iterator does not support remove().@GwtIncompatible(value="Class.isInstance") @CheckReturnValue public static <T> Iterable<T> filter(Iterable<?> unfiltered, Class<T> type)
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().unfiltered - an iterable containing objects of any typetype - the type of elements desiredpublic static <T> boolean any(Iterable<T> iterable, Predicate<? super T> predicate)
true if any element in iterable satisfies the predicate.public static <T> boolean all(Iterable<T> iterable, Predicate<? super T> predicate)
true if every element in iterable satisfies the
 predicate. If iterable is empty, true is returned.public static <T> T find(Iterable<T> iterable, Predicate<? super T> predicate)
iterable that satisfies the given
 predicate; use this method only when such an element is known to exist. If
 it is possible that no element will match, use tryFind(java.lang.Iterable<T>, com.google.common.base.Predicate<? super T>) or
 find(Iterable, Predicate, Object) instead.NoSuchElementException - if no element in iterable matches
     the given predicate@Nullable public static <T> T find(Iterable<? extends T> iterable, Predicate<? super T> predicate, @Nullable T defaultValue)
iterable that satisfies the given
 predicate, or defaultValue if none found. Note that this can
 usually be handled more naturally using tryFind(iterable, predicate).or(defaultValue).public static <T> Optional<T> tryFind(Iterable<T> iterable, Predicate<? super T> predicate)
Optional containing the first element in iterable that satisfies the given predicate, if such an element exists.
 Warning: avoid using a predicate that matches null. If null is matched in iterable, a
 NullPointerException will be thrown.
public static <T> int indexOf(Iterable<T> iterable, Predicate<? super T> predicate)
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)) returns true,
 or -1 if there is no such index.
@CheckReturnValue public static <F,T> Iterable<T> transform(Iterable<F> fromIterable, Function<? super F,? extends T> function)
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.
 
If the input Iterable is known to be a List or other
 Collection, consider Lists.transform(java.util.List<F>, com.google.common.base.Function<? super F, ? extends T>) and Collections2.transform(java.util.Collection<F>, com.google.common.base.Function<? super F, T>).
public static <T> T get(Iterable<T> iterable, int position)
position - position of the element to returniterableIndexOutOfBoundsException - if position is negative or
     greater than or equal to the size of iterable@Nullable public static <T> T get(Iterable<? extends T> iterable, int position, @Nullable T defaultValue)
position - position of the element to returndefaultValue - the default value to return if position is
     greater than or equal to the size of the iterableiterable or
     defaultValue if iterable contains fewer than
     position + 1 elements.IndexOutOfBoundsException - if position is negative@Nullable public static <T> T getFirst(Iterable<? extends T> iterable, @Nullable T defaultValue)
iterable or defaultValue if
 the iterable is empty.  The Iterators analog to this method is
 Iterators.getNext(java.util.Iterator<? extends T>, T).
 If no default value is desired (and the caller instead wants a
 NoSuchElementException to be thrown), it is recommended that
 iterable.iterator().next() is used instead.
defaultValue - the default value to return if the iterable is emptyiterable or the default valuepublic static <T> T getLast(Iterable<T> iterable)
iterable.iterableNoSuchElementException - if the iterable is empty@Nullable public static <T> T getLast(Iterable<? extends T> iterable, @Nullable T defaultValue)
iterable or defaultValue if
 the iterable is empty.defaultValue - the value to return if iterable is emptyiterable or the default valuepublic static <T> Iterable<T> skip(Iterable<T> iterable, int numberToSkip)
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.
public static <T> Iterable<T> limit(Iterable<T> iterable, int limitSize)
limitSize elements of the given
 iterable. If the original iterable does not contain that many elements, the
 returned iterable will have the same behavior as the original iterable. The
 returned iterable's iterator supports remove() if the original
 iterator does.iterable - the iterable to limitlimitSize - the maximum number of elements in the returned iterableIllegalArgumentException - if limitSize is negativepublic static <T> Iterable<T> consumingIterable(Iterable<T> iterable)
Iterator through Iterators.consumingIterator(Iterator).
 Note: If iterable is a Queue, the returned iterable will
 get entries from Queue.remove() since Queue's iteration
 order is undefined.  Calling Iterator.hasNext() on a generated
 iterator from the returned iterable may cause an item to be immediately
 dequeued for return on a subsequent call to Iterator.next().
iterable - the iterable to wrapIterators.consumingIterator(Iterator); for queues,
     an iterable that generates iterators that return and consume the
     queue's elements in queue orderIterators.consumingIterator(Iterator)public static boolean isEmpty(Iterable<?> iterable)
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()).
true if the iterable contains no elements@Beta public static <T> Iterable<T> mergeSorted(Iterable<? extends Iterable<? extends T>> iterables, Comparator<? super T> comparator)
iterables. Equivalent entries will not be de-duplicated.
 Callers must ensure that the source iterables are in
 non-descending order as this method does not sort its input.
 
For any equivalent elements across all iterables, it is
 undefined which element is returned first.
Copyright © 2010-2015. All Rights Reserved.