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
  Version:
    $Id: IterableUtils.java 1716538 2015-11-25 20:27:49Z tn $

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IterableUtils()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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(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> 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> 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 <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>... 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 <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> first, Iterable<? extends E>... others)` Interleaves two iterables into a single iterable.
    `static <E> Iterable<E>` | `zippingIterable(Iterable<? extends E> a, Iterable<? extends E> b)` 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 Detail

    - #### IterableUtils

          public IterableUtils()

  - ### Method Detail

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.