Package org.apache.commons.collections4

# Class IterableUtils

java.lang.Object
org.apache.commons.collections4.IterableUtils

public class IterableUtils extends Object
Provides utility methods and decorators for `Iterable` instances.

Note: this util class has been designed for fail-fast argument checking.

- all decorator methods are NOT null-safe wrt the provided Iterable argument, i.e. they will throw a `NullPointerException` if a null Iterable is passed as argument.
- all other utility methods are null-safe wrt the provided Iterable argument, i.e. they will treat a null Iterable the same way as an empty one. Other arguments which are null, e.g. a `Predicate`, will result in a `NullPointerException`. Exception: passing a null `Comparator` is equivalent to a Comparator with natural ordering.

Since:
  4.1

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `IterableUtils()`
  Deprecated.
  TODO Make private in 5.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E> Iterable<E>`
  `boundedIterable(Iterable<E> iterable, long maxSize)`
  Returns a view of the given iterable that contains at most the given number of elements.
  `static <E> Iterable<E>`
  `chainedIterable(Iterable<? extends E>... iterables)`
  Combines the provided iterables into a single iterable.
  `static <E> Iterable<E>`
  `chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b)`
  Combines two iterables into a single iterable.
  `static <E> Iterable<E>`
  `chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c)`
  Combines three iterables into a single iterable.
  `static <E> Iterable<E>`
  `chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c, Iterable<? extends E> d)`
  Combines four iterables into a single iterable.
  `static <E> Iterable<E>`
  `collatedIterable(Iterable<? extends E> a, Iterable<? extends E> b)`
  Combines the two provided iterables into an ordered iterable using natural ordering.
  `static <E> Iterable<E>`
  `collatedIterable(Comparator<? super E> comparator, Iterable<? extends E> a, Iterable<? extends E> b)`
  Combines the two provided iterables into an ordered iterable using the provided comparator.
  `static <E> boolean`
  `contains(Iterable<? extends E> iterable, E object, Equator<? super E> equator)`
  Checks if the object is contained in the given iterable.
  `static <E> boolean`
  `contains(Iterable<E> iterable, Object object)`
  Checks if the object is contained in the given iterable.
  `static <E> long`
  `countMatches(Iterable<E> input, Predicate<? super E> predicate)`
  Counts the number of elements in the input iterable that match the predicate.
  `static <E> Iterable<E>`
  `emptyIfNull(Iterable<E> iterable)`
  Returns an immutable empty iterable if the argument is null, or the argument itself otherwise.
  `static <E> Iterable<E>`
  `emptyIterable()`
  Gets an empty iterable.
  `static <E> Iterable<E>`
  `filteredIterable(Iterable<E> iterable, Predicate<? super E> predicate)`
  Returns a view of the given iterable that only contains elements matching the provided predicate.
  `static <E> E`
  `find(Iterable<E> iterable, Predicate<? super E> predicate)`
  Finds the first element in the given iterable which matches the given predicate.
  `static <T> T`
  `first(Iterable<T> iterable)`
  Shortcut for `get(iterator, 0)`.
  `static <E> void`
  `forEach(Iterable<E> iterable, Closure<? super E> closure)`
  Applies the closure to each element of the provided iterable.
  `static <E> E`
  `forEachButLast(Iterable<E> iterable, Closure<? super E> closure)`
  Executes the given closure on each but the last element in the iterable.
  `static <E, T extends E>
  int`
  `frequency(Iterable<E> iterable, T obj)`
  Returns the number of occurrences of the provided object in the iterable.
  `static <T> T`
  `get(Iterable<T> iterable, int index)`
  Returns the `index`-th value in the `iterable`'s `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.
  `static <E> int`
  `indexOf(Iterable<E> iterable, Predicate<? super E> predicate)`
  Returns the index of the first element in the specified iterable that matches the given predicate.
  `static boolean`
  `isEmpty(Iterable<?> iterable)`
  Answers true if the provided iterable is empty.
  `static <E> Iterable<E>`
  `loopingIterable(Iterable<E> iterable)`
  Returns a view of the given iterable which will cycle infinitely over its elements.
  `static <E> boolean`
  `matchesAll(Iterable<E> iterable, Predicate<? super E> predicate)`
  Answers true if a predicate is true for every element of an iterable.
  `static <E> boolean`
  `matchesAny(Iterable<E> iterable, Predicate<? super E> predicate)`
  Answers true if a predicate is true for any element of the iterable.
  `static <O, R extends Collection<O>>
  List<R>`
  `partition(Iterable<? extends O> iterable, Factory<R> partitionFactory, Predicate<? super O>... predicates)`
  Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicates.
  `static <O> List<List<O>>`
  `partition(Iterable<? extends O> iterable, Predicate<? super O> predicate)`
  Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicate.
  `static <O> List<List<O>>`
  `partition(Iterable<? extends O> iterable, Predicate<? super O>... predicates)`
  Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicates.
  `static <E> Iterable<E>`
  `reversedIterable(Iterable<E> iterable)`
  Returns a reversed view of the given iterable.
  `static int`
  `size(Iterable<?> iterable)`
  Returns the number of elements contained in the given iterator.
  `static <E> Iterable<E>`
  `skippingIterable(Iterable<E> iterable, long elementsToSkip)`
  Returns a view of the given iterable that skips the first N elements.
  `static <E> List<E>`
  `toList(Iterable<E> iterable)`
  Gets a new list with the contents of the provided iterable.
  `static <E> String`
  `toString(Iterable<E> iterable)`
  Returns a string representation of the elements of the specified iterable.
  `static <E> String`
  `toString(Iterable<E> iterable, Transformer<? super E,String> transformer)`
  Returns a string representation of the elements of the specified iterable.
  `static <E> String`
  `toString(Iterable<E> iterable, Transformer<? super E,String> transformer, String delimiter, String prefix, String suffix)`
  Returns a string representation of the elements of the specified iterable.
  `static <I, O> Iterable<O>`
  `transformedIterable(Iterable<I> iterable, Transformer<? super I,? extends O> transformer)`
  Returns a transformed view of the given iterable where all of its elements have been transformed by the provided transformer.
  `static <E> Iterable<E>`
  `uniqueIterable(Iterable<E> iterable)`
  Returns a unique view of the given iterable.
  `static <E> Iterable<E>`
  `unmodifiableIterable(Iterable<E> iterable)`
  Returns an unmodifiable view of the given iterable.
  `static <E> Iterable<E>`
  `zippingIterable(Iterable<? extends E> a, Iterable<? extends E> b)`
  Interleaves two iterables into a single iterable.
  `static <E> Iterable<E>`
  `zippingIterable(Iterable<? extends E> first, Iterable<? extends E>... others)`
  Interleaves two iterables into a single iterable.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### IterableUtils

    @Deprecated public IterableUtils()
    Deprecated.
    TODO Make private in 5.0.
    Make private in 5.0.

- ## Method Details

  - ### boundedIterable

    public static <E> Iterable<E> boundedIterable(Iterable<E> iterable, long maxSize)
    Returns a view of the given iterable that contains at most the given number of elements.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to limit, may not be null
      `maxSize` - the maximum number of elements, must not be negative
    Returns:
      a bounded view on the specified iterable
    Throws:
      `IllegalArgumentException` - if maxSize is negative
      `NullPointerException` - if iterable is null

  - ### chainedIterable

    public static <E> Iterable<E> chainedIterable(Iterable<? extends E>... iterables)
    Combines the provided iterables into a single iterable.

    The returned iterable has an iterator that traverses the elements in the order of the arguments, i.e. iterables[0], iterables[1], .... The source iterators are not polled until necessary.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterables` - the iterables to combine, may not be null
    Returns:
      a new iterable, combining the provided iterables
    Throws:
      `NullPointerException` - if either of the provided iterables is null

  - ### chainedIterable

    public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> 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.

    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterable, may not be null
      `b` - the second iterable, may not be null
    Returns:
      a new iterable, combining the provided iterables
    Throws:
      `NullPointerException` - if either a or b is null

  - ### chainedIterable

    public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> 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` and `c`. The source iterators are not polled until necessary.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterable, may not be null
      `b` - the second iterable, may not be null
      `c` - the third iterable, may not be null
    Returns:
      a new iterable, combining the provided iterables
    Throws:
      `NullPointerException` - if either of the provided iterables is null

  - ### chainedIterable

    public static <E> Iterable<E> chainedIterable(Iterable<? extends E> a, Iterable<? extends E> b, Iterable<? extends E> c, Iterable<? extends E> 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`, `c` and `d`. The source iterators are not polled until necessary.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterable, may not be null
      `b` - the second iterable, may not be null
      `c` - the third iterable, may not be null
      `d` - the fourth iterable, may not be null
    Returns:
      a new iterable, combining the provided iterables
    Throws:
      `NullPointerException` - if either of the provided iterables is null

  - ### collatedIterable

    public static <E> Iterable<E> collatedIterable(Comparator<? super E> comparator, Iterable<? extends E> a, Iterable<? extends E> b)
    Combines the two provided iterables into an ordered iterable using the provided comparator. If the comparator is null, natural ordering will be used.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `comparator` - the comparator defining an ordering over the elements, may be null, in which case natural ordering will be used
      `a` - the first iterable, may not be null
      `b` - the second iterable, may not be null
    Returns:
      a filtered view on the specified iterable
    Throws:
      `NullPointerException` - if either of the provided iterables is null

  - ### collatedIterable

    public static <E> Iterable<E> collatedIterable(Iterable<? extends E> a, Iterable<? extends E> b)
    Combines the two provided iterables into an ordered iterable using natural ordering.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterable, must not be null
      `b` - the second iterable, must not be null
    Returns:
      a filtered view on the specified iterable
    Throws:
      `NullPointerException` - if either of the provided iterables is null

  - ### contains

    public static <E> boolean contains(Iterable<? extends E> iterable, E object, Equator<? super E> equator)
    Checks if the object is contained in the given iterable. Object equality is tested with an `equator` unlike `contains(Iterable, Object)` which uses `Object.equals(Object)`.

    A `null` or empty iterable returns false. A `null` object will not be passed to the equator, instead a `NullPredicate` will be used.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the iterable to check, may be null
      `object` - the object to check
      `equator` - the equator to use to check, may not be null
    Returns:
      true if the object is contained in the iterable, false otherwise
    Throws:
      `NullPointerException` - if equator is null

  - ### contains

    public static <E> boolean contains(Iterable<E> iterable, Object object)
    Checks if the object is contained in the given iterable.

    A `null` or empty iterable returns false.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the iterable to check, may be null
      `object` - the object to check
    Returns:
      true if the object is contained in the iterable, false otherwise

  - ### countMatches

    public static <E> long countMatches(Iterable<E> input, Predicate<? super E> predicate)
    Counts the number of elements in the input iterable that match the predicate.

    A `null` iterable matches no elements.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `input` - the `Iterable` to get the input from, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      the number of matches for the predicate in the collection
    Throws:
      `NullPointerException` - if predicate is null

  - ### emptyIfNull

    public static <E> Iterable<E> emptyIfNull(Iterable<E> iterable)
    Returns an immutable empty iterable if the argument is null, or the argument itself otherwise.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable, may be null
    Returns:
      an empty iterable if the argument is null

  - ### emptyIterable

    public static <E> Iterable<E> emptyIterable()
    Gets an empty iterable.

    This iterable does not contain any elements.

    Type Parameters:
      `E` - the element type
    Returns:
      an empty iterable

  - ### filteredIterable

    public static <E> Iterable<E> filteredIterable(Iterable<E> iterable, Predicate<? super E> predicate)
    Returns a view of the given iterable that only contains elements matching the provided predicate.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to filter, may not be null
      `predicate` - the predicate used to filter elements, may not be null
    Returns:
      a filtered view on the specified iterable
    Throws:
      `NullPointerException` - if either iterable or predicate is null

  - ### find

    public static <E> E find(Iterable<E> iterable, Predicate<? super E> predicate)
    Finds the first element in the given iterable which matches the given predicate.

    A `null` or empty iterator returns null.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to search, may be null
      `predicate` - the predicate to use, must not be null
    Returns:
      the first element of the iterable which matches the predicate or null if none could be found
    Throws:
      `NullPointerException` - if predicate is null

  - ### first

    public static <T> T first(Iterable<T> iterable)
    Shortcut for `get(iterator, 0)`.

    Returns the `first` value in the `iterable`'s `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

    If the `Iterable` is a `List`, then it will use `List.get(int)`.

    Type Parameters:
      `T` - the type of object in the `Iterable`.
    Parameters:
      `iterable` - the `Iterable` to get a value from, may be null
    Returns:
      the first object
    Throws:
      `IndexOutOfBoundsException` - if the request is invalid
    Since:
      4.2

  - ### forEach

    public static <E> void forEach(Iterable<E> iterable, Closure<? super E> closure)
    Applies the closure to each element of the provided iterable.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterator to use, may be null
      `closure` - the closure to apply to each element, may not be null
    Throws:
      `NullPointerException` - if closure is null

  - ### forEachButLast

    public static <E> E forEachButLast(Iterable<E> iterable, Closure<? super E> closure)
    Executes the given closure on each but the last element in the iterable.

    If the input iterable is null no change is made.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the iterable to get the input from, may be null
      `closure` - the closure to perform, may not be null
    Returns:
      the last element in the iterable, or null if iterable is null or empty

  - ### frequency

    public static <E, T extends E> int frequency(Iterable<E> iterable, T obj)
    Returns the number of occurrences of the provided object in the iterable.
    Type Parameters:
      `E` - the element type that the `Iterable` may contain
      `T` - the element type of the object to find
    Parameters:
      `iterable` - the `Iterable` to search
      `obj` - the object to find the cardinality of
    Returns:
      the number of occurrences of obj in iterable

  - ### get

    public static <T> T get(Iterable<T> iterable, int index)
    Returns the `index`-th value in the `iterable`'s `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

    If the `Iterable` is a `List`, then it will use `List.get(int)`.

    Type Parameters:
      `T` - the type of object in the `Iterable`.
    Parameters:
      `iterable` - the `Iterable` to get a value from, may be null
      `index` - the index to get
    Returns:
      the object at the specified index
    Throws:
      `IndexOutOfBoundsException` - if the index is invalid

  - ### indexOf

    public static <E> int indexOf(Iterable<E> iterable, Predicate<? super E> predicate)
    Returns the index of the first element in the specified iterable that matches the given predicate.

    A `null` or empty iterable returns -1.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to search, may be null
      `predicate` - the predicate to use, must not be null
    Returns:
      the index of the first element which matches the predicate or -1 if none matches
    Throws:
      `NullPointerException` - if predicate is null

  - ### isEmpty

    public static boolean isEmpty(Iterable<?> iterable)
    Answers true if the provided iterable is empty.

    A `null` iterable returns true.

    Parameters:
      `iterable` - the `to use`, may be null
    Returns:
      true if the iterable is null or empty, false otherwise

  - ### loopingIterable

    public static <E> Iterable<E> loopingIterable(Iterable<E> iterable)
    Returns a view of the given iterable which will cycle infinitely over its elements.

    The returned iterable's 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.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to loop, may not be null
    Returns:
      a view of the iterable, providing an infinite loop over its elements
    Throws:
      `NullPointerException` - if iterable is null

  - ### matchesAll

    public static <E> boolean matchesAll(Iterable<E> iterable, Predicate<? super E> predicate)
    Answers true if a predicate is true for every element of an iterable.

    A `null` or empty iterable returns true.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the `Iterable` to use, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      true if every element of the collection matches the predicate or if the collection is empty, false otherwise
    Throws:
      `NullPointerException` - if predicate is null

  - ### matchesAny

    public static <E> boolean matchesAny(Iterable<E> iterable, Predicate<? super E> predicate)
    Answers true if a predicate is true for any element of the iterable.

    A `null` or empty iterable returns false.

    Type Parameters:
      `E` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the `Iterable` to use, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      true if any element of the collection matches the predicate, false otherwise
    Throws:
      `NullPointerException` - if predicate is null

  - ### partition

    public static <O, R extends Collection<O>> List<R> partition(Iterable<? extends O> iterable, Factory<R> partitionFactory, Predicate<? super O>... predicates)
    Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicates.

    For each predicate, the returned list will contain a collection holding all elements of the input iterable matching the predicate. The last collection contained in the list will hold all elements which didn't match any predicate:

          [C1, C2, R] = partition(I, P1, P2) with
          I = input
          P1 = first predicate
          P2 = second predicate
          C1 = collection of elements matching P1
          C2 = collection of elements matching P2
          R = collection of elements rejected by all predicates

    Note: elements are only added to the output collection of the first matching predicate, determined by the order of arguments.

    If the input iterable is `null`, the same is returned as for an empty iterable. If no predicates have been provided, all elements of the input collection will be added to the rejected collection.

    Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].

    Type Parameters:
      `O` - the type of object the `Iterable` contains
      `R` - the type of the output `Collection`
    Parameters:
      `iterable` - the collection to get the input from, may be null
      `partitionFactory` - the factory used to create the output collections
      `predicates` - the predicates to use, may not be null
    Returns:
      a list containing the output collections
    Throws:
      `NullPointerException` - if any predicate is null

  - ### partition

    public static <O> List<List<O>> partition(Iterable<? extends O> iterable, Predicate<? super O> predicate)
    Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicate.

    For each predicate, the result will contain a list holding all elements of the input iterable matching the predicate. The last list will hold all elements which didn't match any predicate:

          [C1, R] = partition(I, P1) with
          I = input
          P1 = first predicate
          C1 = collection of elements matching P1
          R = collection of elements rejected by all predicates

    If the input iterable is `null`, the same is returned as for an empty iterable.

    Example: for an input list [1, 2, 3, 4, 5] calling partition with a predicate [x < 3] will result in the following output: [[1, 2], [3, 4, 5]].

    Type Parameters:
      `O` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the iterable to partition, may be null
      `predicate` - the predicate to use, may not be null
    Returns:
      a list containing the output collections
    Throws:
      `NullPointerException` - if predicate is null

  - ### partition

    public static <O> List<List<O>> partition(Iterable<? extends O> iterable, Predicate<? super O>... predicates)
    Partitions all elements from iterable into separate output collections, based on the evaluation of the given predicates.

    For each predicate, the result will contain a list holding all elements of the input iterable matching the predicate. The last list will hold all elements which didn't match any predicate:

          [C1, C2, R] = partition(I, P1, P2) with
          I = input
          P1 = first predicate
          P2 = second predicate
          C1 = collection of elements matching P1
          C2 = collection of elements matching P2
          R = collection of elements rejected by all predicates

    Note: elements are only added to the output collection of the first matching predicate, determined by the order of arguments.

    If the input iterable is `null`, the same is returned as for an empty iterable.

    Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]].

    Type Parameters:
      `O` - the type of object the `Iterable` contains
    Parameters:
      `iterable` - the collection to get the input from, may be null
      `predicates` - the predicates to use, may not be null
    Returns:
      a list containing the output collections
    Throws:
      `NullPointerException` - if any predicate is null

  - ### reversedIterable

    public static <E> Iterable<E> reversedIterable(Iterable<E> iterable)
    Returns a reversed view of the given iterable.

    In case the provided iterable is a `List` instance, a `ReverseListIterator` will be used to reverse the traversal order, otherwise an intermediate `List` needs to be created.

    The returned iterable's iterator supports `remove()` if the provided iterable is a `List` instance.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to use, may not be null
    Returns:
      a reversed view of the specified iterable
    Throws:
      `NullPointerException` - if iterable is null
    See Also:
      - `ReverseListIterator`

  - ### size

    public static int size(Iterable<?> iterable)
    Returns the number of elements contained in the given iterator.

    A `null` or empty iterator returns `0`.

    Parameters:
      `iterable` - the iterable to check, may be null
    Returns:
      the number of elements contained in the iterable

  - ### skippingIterable

    public static <E> Iterable<E> skippingIterable(Iterable<E> iterable, long elementsToSkip)
    Returns a view of the given iterable that skips the first N elements.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to use, may not be null
      `elementsToSkip` - the number of elements to skip from the start, must not be negative
    Returns:
      a view of the specified iterable, skipping the first N elements
    Throws:
      `IllegalArgumentException` - if elementsToSkip is negative
      `NullPointerException` - if iterable is null

  - ### toList

    public static <E> List<E> toList(Iterable<E> iterable)
    Gets a new list with the contents of the provided iterable.
    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to use, may be null
    Returns:
      a list of the iterator contents

  - ### toString

    public static <E> String toString(Iterable<E> iterable)
    Returns a string representation of the elements of the specified iterable.

    The string representation consists of a list of the iterable's elements, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Elements are converted to strings as by `String.valueOf(Object)`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to convert to a string, may be null
    Returns:
      a string representation of `iterable`

  - ### toString

    public static <E> String toString(Iterable<E> iterable, Transformer<? super E,String> transformer)
    Returns a string representation of the elements of the specified iterable.

    The string representation consists of a list of the iterable's elements, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (a comma followed by a space). Elements are converted to strings as by using the provided `transformer`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to convert to a string, may be null
      `transformer` - the transformer used to get a string representation of an element
    Returns:
      a string representation of `iterable`
    Throws:
      `NullPointerException` - if `transformer` is null

  - ### toString

    public static <E> String toString(Iterable<E> iterable, Transformer<? super E,String> transformer, String delimiter, String prefix, String suffix)
    Returns a string representation of the elements of the specified iterable.

    The string representation consists of a list of the iterable's elements, enclosed by the provided `prefix` and `suffix`. Adjacent elements are separated by the provided `delimiter`. Elements are converted to strings as by using the provided `transformer`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to convert to a string, may be null
      `transformer` - the transformer used to get a string representation of an element
      `delimiter` - the string to delimit elements
      `prefix` - the prefix, prepended to the string representation
      `suffix` - the suffix, appended to the string representation
    Returns:
      a string representation of `iterable`
    Throws:
      `NullPointerException` - if either transformer, delimiter, prefix or suffix is null

  - ### transformedIterable

    public static <I, O> Iterable<O> transformedIterable(Iterable<I> iterable, Transformer<? super I,? extends O> transformer)
    Returns a transformed view of the given iterable where all of its elements have been transformed by the provided transformer.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `I` - the input element type
      `O` - the output element type
    Parameters:
      `iterable` - the iterable to transform, may not be null
      `transformer` - the transformer, must not be null
    Returns:
      a transformed view of the specified iterable
    Throws:
      `NullPointerException` - if either iterable or transformer is null

  - ### uniqueIterable

    public static <E> Iterable<E> uniqueIterable(Iterable<E> iterable)
    Returns a unique view of the given iterable.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it. Calling `remove()` will only remove a single element from the underlying iterator.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to use, may not be null
    Returns:
      a unique view of the specified iterable
    Throws:
      `NullPointerException` - if iterable is null

  - ### unmodifiableIterable

    public static <E> Iterable<E> unmodifiableIterable(Iterable<E> iterable)
    Returns an unmodifiable view of the given iterable.

    The returned iterable's iterator does not support `remove()`.

    Type Parameters:
      `E` - the element type
    Parameters:
      `iterable` - the iterable to use, may not be null
    Returns:
      an unmodifiable view of the specified iterable
    Throws:
      `NullPointerException` - if iterable is null

  - ### zippingIterable

    public static <E> Iterable<E> zippingIterable(Iterable<? extends E> a, Iterable<? extends E> b)
    Interleaves two iterables into a single iterable.

    The returned iterable has an iterator that traverses the elements in `a` and `b` in alternating order. The source iterators are not polled until necessary.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `a` - the first iterable, may not be null
      `b` - the second iterable, may not be null
    Returns:
      a new iterable, interleaving the provided iterables
    Throws:
      `NullPointerException` - if either a or b is null

  - ### zippingIterable

    public static <E> Iterable<E> zippingIterable(Iterable<? extends E> first, Iterable<? extends E>... others)
    Interleaves two iterables into a single iterable.

    The returned iterable has an iterator that traverses the elements in `a` and `b` in alternating order. The source iterators are not polled until necessary.

    The returned iterable's iterator supports `remove()` when the corresponding input iterator supports it.

    Type Parameters:
      `E` - the element type
    Parameters:
      `first` - the first iterable, may not be null
      `others` - the array of iterables to interleave, may not be null
    Returns:
      a new iterable, interleaving the provided iterables
    Throws:
      `NullPointerException` - if either of the provided iterables is null