Iterables
Date: 2016-05-24

com.google.common.collect

## Class Iterables

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

-     @GwtCompatible(emulated=true)
      public final class Iterables
      extends java.lang.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.

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

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> boolean` | `addAll(java.util.Collection<T> addTo, java.lang.Iterable<? extends T> elementsToAdd)` 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 any element in `iterable` satisfies 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 <T> java.lang.Iterable<T>` | `concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c)` Combines three iterables into a single iterable.
    `static <T> java.lang.Iterable<T>` | `concat(java.lang.Iterable<? extends T> a, java.lang.Iterable<? extends T> b, java.lang.Iterable<? extends T> c, java.lang.Iterable<? extends T> d)` Combines four iterables into a single iterable.
    `static <T> java.lang.Iterable<T>` | `consumingIterable(java.lang.Iterable<T> iterable)` Returns a view of the supplied iterable that wraps each generated `Iterator` through `Iterators.consumingIterator(Iterator)`.
    `static boolean` | `contains(java.lang.Iterable<?> iterable, java.lang.Object element)` Returns `true` if `iterable` contains any object for which `equals(element)` is true.
    `static <T> java.lang.Iterable<T>` | `cycle(java.lang.Iterable<T> iterable)` Returns an iterable whose iterators cycle indefinitely over the elements of `iterable`.
    `static <T> java.lang.Iterable<T>` | `cycle(T... elements)` Returns an iterable whose iterators cycle 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>` | `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 <T> T` | `find(java.lang.Iterable<? extends T> iterable, Predicate<? super T> predicate, T defaultValue)` Returns the first element in `iterable` that satisfies the given predicate, or `defaultValue` if none found.
    `static <T> T` | `find(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)` Returns the first element in `iterable` that satisfies the given predicate; use this method only when such an element is known to exist.
    `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<? 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(java.lang.Iterable<T> iterable, int position)` Returns the element at the specified position in an iterable.
    `static <T> T` | `getFirst(java.lang.Iterable<? extends T> iterable, T defaultValue)` Returns the first element in `iterable` or `defaultValue` if the iterable is empty.
    `static <T> T` | `getLast(java.lang.Iterable<? extends T> iterable, T defaultValue)` Returns the last element of `iterable` or `defaultValue` if the iterable is empty.
    `static <T> T` | `getLast(java.lang.Iterable<T> iterable)` Returns the last element of `iterable`.
    `static <T> T` | `getOnlyElement(java.lang.Iterable<? extends T> iterable, T defaultValue)` Returns the single element contained in `iterable`, or `defaultValue` if the iterable is empty.
    `static <T> T` | `getOnlyElement(java.lang.Iterable<T> iterable)` Returns the single element contained in `iterable`.
    `static <T> int` | `indexOf(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)` Returns the index in `iterable` of the first element that satisfies the provided `predicate`, or `-1` if the Iterable has no such elements.
    `static boolean` | `isEmpty(java.lang.Iterable<?> iterable)` Determines if 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> java.lang.Iterable<T>` | `mergeSorted(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables, java.util.Comparator<? super T> comparator)` Returns an iterable over the merged contents of all given `iterables`.
    `static <T> java.lang.Iterable<java.util.List<T>>` | `paddedPartition(java.lang.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> java.lang.Iterable<java.util.List<T>>` | `partition(java.lang.Iterable<T> iterable, int size)` Divides an iterable into unmodifiable sublists of the given size (the final iterable may be smaller).
    `static boolean` | `removeAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRemove)` Removes, from an iterable, every element that belongs to the provided collection.
    `static <T> boolean` | `removeIf(java.lang.Iterable<T> removeFrom, Predicate<? super T> predicate)` Removes, from an iterable, every element that satisfies the provided predicate.
    `static boolean` | `retainAll(java.lang.Iterable<?> removeFrom, java.util.Collection<?> elementsToRetain)` Removes, from an iterable, every element that does not belong to the provided collection.
    `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 <T> T[]` | `toArray(java.lang.Iterable<? extends T> iterable, java.lang.Class<T> type)` Copies an iterable's elements into an array.
    `static java.lang.String` | `toString(java.lang.Iterable<?> iterable)` Returns a string representation of `iterable`, with the format `[e1, e2, ..., en]` (that is, identical to `Arrays``.toString(Iterables.toArray(iterable))`).
    `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> Optional<T>` | `tryFind(java.lang.Iterable<T> iterable, Predicate<? super T> predicate)` Returns an `Optional` containing the first element in `iterable` that satisfies the given predicate, if such an element exists.
    `static <E> java.lang.Iterable<E>` | `unmodifiableIterable(ImmutableCollection<E> iterable)` Deprecated. no need to use this
    `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

    - #### unmodifiableIterable

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

      Returns an unmodifiable view of `iterable`.

    - #### unmodifiableIterable

          @Deprecated
          public static <E> java.lang.Iterable<E> unmodifiableIterable(ImmutableCollection<E> iterable)

      Deprecated. no need to use this
      Simply returns its argument.
      Since:
        10.0

    - #### 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 any object for which `equals(element)` is true.

    - #### removeAll

          public static boolean removeAll(java.lang.Iterable<?> removeFrom,
                          java.util.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 element was removed from `iterable`

    - #### retainAll

          public static boolean retainAll(java.lang.Iterable<?> removeFrom,
                          java.util.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 element was removed from `iterable`

    - #### removeIf

          public static <T> boolean removeIf(java.lang.Iterable<T> removeFrom,
                             Predicate<? super T> predicate)

      Removes, from an iterable, every element that satisfies the provided predicate.
      Parameters:
        `removeFrom` - the iterable to (potentially) remove elements from
        `predicate` - a predicate that determines whether an element should be removed
      Returns:
        `true` if any elements were removed from the iterable
      Throws:
        `java.lang.UnsupportedOperationException` - if the iterable does not support `remove()`.
      Since:
        2.0

    - #### elementsEqual

          @CheckReturnValue
          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]` (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.

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

          @Nullable
          public static <T> T getOnlyElement(java.lang.Iterable<? extends 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

    - #### toArray

          @GwtIncompatible(value="Array.newInstance(Class, int)")
          public static <T> T[] toArray(java.lang.Iterable<? extends 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> addTo,
                           java.lang.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(java.lang.Iterable<?> iterable,
                      @Nullable
                      java.lang.Object element)

      Returns the number of elements in the specified iterable that equal the specified object. This implementation avoids a full iteration when the iterable is a `Multiset` or `Set`.
      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 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> java.lang.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> 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> a,
                                         java.lang.Iterable<? extends T> b,
                                         java.lang.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> java.lang.Iterable<T> concat(java.lang.Iterable<? extends T> a,
                                         java.lang.Iterable<? extends T> b,
                                         java.lang.Iterable<? extends T> c,
                                         java.lang.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> 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 is null.

    - #### partition

          public static <T> java.lang.Iterable<java.util.List<T>> partition(java.lang.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:
        `java.lang.IllegalArgumentException` - if `size` is nonpositive

    - #### paddedPartition

          public static <T> java.lang.Iterable<java.util.List<T>> paddedPartition(java.lang.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:
        `java.lang.IllegalArgumentException` - if `size` is nonpositive

    - #### filter

          @CheckReturnValue
          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

          @GwtIncompatible(value="Class.isInstance")
          @CheckReturnValue
          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 any element in `iterable` satisfies 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 <T> T find(java.lang.Iterable<T> iterable,
                   Predicate<? super T> predicate)

      Returns the first element in `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.
      Throws:
        `java.util.NoSuchElementException` - if no element in `iterable` matches the given predicate

    - #### find

          @Nullable
          public static <T> T find(java.lang.Iterable<? extends T> iterable,
                            Predicate<? super T> predicate,
                            @Nullable
                            T defaultValue)

      Returns the first element in `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)`.
      Since:
        7.0

    - #### tryFind

          public static <T> Optional<T> tryFind(java.lang.Iterable<T> iterable,
                                Predicate<? super T> predicate)

      Returns an `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.

      Since:
        11.0

    - #### indexOf

          public static <T> int indexOf(java.lang.Iterable<T> iterable,
                        Predicate<? super T> predicate)

      Returns the index in `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.

      Since:
        2.0

    - #### transform

          @CheckReturnValue
          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.

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

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

    - #### get

          @Nullable
          public static <T> T get(java.lang.Iterable<? extends T> iterable,
                           int position,
                           @Nullable
                           T defaultValue)

      Returns the element at the specified position in an iterable or a default value otherwise.
      Parameters:
        `position` - position of the element to return
        `defaultValue` - the default value to return if `position` is greater than or equal to the size of the iterable
      Returns:
        the element at the specified position in `iterable` or `defaultValue` if `iterable` contains fewer than `position + 1` elements.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if `position` is negative
      Since:
        4.0

    - #### getFirst

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

      Returns the first element in `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.

      Parameters:
        `defaultValue` - the default value to return if the iterable is empty
      Returns:
        the first element of `iterable` or the default value
      Since:
        7.0

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

    - #### getLast

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

      Returns the last element of `iterable` or `defaultValue` if the iterable is empty.
      Parameters:
        `defaultValue` - the value to return if `iterable` is empty
      Returns:
        the last element of `iterable` or the default value
      Since:
        3.0

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

      Since:
        3.0

    - #### 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 iterable 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 iterable
      Throws:
        `java.lang.IllegalArgumentException` - if `limitSize` is negative
      Since:
        3.0

    - #### consumingIterable

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

      Returns a view of the supplied iterable that wraps each generated `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()`.

      Parameters:
        `iterable` - the iterable to wrap
      Returns:
        a view of the supplied iterable that wraps each generated iterator through `Iterators.consumingIterator(Iterator)`; for queues, an iterable that generates iterators that return and consume the queue's elements in queue order
      Since:
        2.0
      See Also:
        `Iterators.consumingIterator(Iterator)`

    - #### isEmpty

          public static boolean isEmpty(java.lang.Iterable<?> 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

    - #### mergeSorted

          @Beta
          public static <T> java.lang.Iterable<T> mergeSorted(java.lang.Iterable<? extends java.lang.Iterable<? extends T>> iterables,
                                                   java.util.Comparator<? super T> comparator)

      Returns an iterable over the merged contents of all given `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.

      Since:
        11.0