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 utility class has been designed with fail-fast argument checking.

- All decorator methods are not null-safe for the provided Iterable argument; for example, they will throw a `NullPointerException` if a null Iterable is passed as argument.
- All other utility methods are null-safe for the provided Iterable argument; for example, they will treat a null Iterable the same way as an empty one. For other arguments which are null, 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> List<E>`
  `duplicateList(Iterable<E> iterable)`
  Finds and returns the List of duplicate elements in the given collection.
  `static <E> Set<E>`
  `duplicateSequencedSet(Iterable<E> iterable)`
  Finds and returns the sequenced Set of duplicate elements in the given collection.
  `static <E> Set<E>`
  `duplicateSet(Iterable<E> iterable)`
  Finds and returns the set of duplicate elements in the given collection.
  `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)`
  Gets 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> int`
  `sumSizesToInt(Iterable<? extends Collection<E>> iterable)`
  Returns the sum of the sizes of the collections in the given iterable.
  `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.

  - ### duplicateList

    public static <E> List<E> duplicateList(Iterable<E> iterable)
    Finds and returns the List of duplicate elements in the given collection.
    Type Parameters:
      `E` - The type of elements in the collection.
    Parameters:
      `iterable` - The list to test, must not be null.
    Returns:
      The set of duplicate elements, may be empty.
    Throws:
      `NullPointerException` - if iterable is null.
    Since:
      4.5.0-M3

  - ### duplicateSequencedSet

    public static <E> Set<E> duplicateSequencedSet(Iterable<E> iterable)
    Finds and returns the sequenced Set of duplicate elements in the given collection.

    Once we are on Java 21 and a new major version, the return type should be SequencedSet.

    Type Parameters:
      `E` - The type of elements in the collection.
    Parameters:
      `iterable` - The list to test, must not be null.
    Returns:
      The set of duplicate elements, may be empty.
    Throws:
      `NullPointerException` - if iterable is null.
    Since:
      4.5.0-M3

  - ### duplicateSet

    public static <E> Set<E> duplicateSet(Iterable<E> iterable)
    Finds and returns the set of duplicate elements in the given collection.
    Type Parameters:
      `E` - The type of elements in the collection.
    Parameters:
      `iterable` - The list to test, must not be null.
    Returns:
      The set of duplicate elements, may be empty.
    Throws:
      `NullPointerException` - if iterable is null.
    Since:
      4.5.0-M3

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

  - ### sumSizesToInt

    public static <E> int sumSizesToInt(Iterable<? extends Collection<E>> iterable)
    Returns the sum of the sizes of the collections in the given iterable.

    Integer overflow is capped at `Integer.MAX_VALUE`.

    Type Parameters:
      `E` - The element type of the collections in the iterable.
    Parameters:
      `iterable` - The iterable of collections to sum the sizes of, must not be null.
    Returns:
      The sum of the sizes of the collections in the iterable, capped at `Integer.MAX_VALUE`.
    Throws:
      `NullPointerException` - if iterable is null.
    Since:
      4.6.0

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