Package org.apache.commons.collections4

Class IterableUtils

  • public class IterableUtils
extends java.lang.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()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <E> java.lang.Iterable<E> boundedIterable​(java.lang.Iterable<E> iterable, long maxSize)
      Returns a view of the given iterable that contains at most the given number of elements.
      static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E>... iterables)
      Combines the provided iterables into a single iterable.
      static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b)
      Combines two iterables into a single iterable.
      static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b, java.lang.Iterable<? extends E> c)
      Combines three iterables into a single iterable.
      static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b, java.lang.Iterable<? extends E> c, java.lang.Iterable<? extends E> d)
      Combines four iterables into a single iterable.
      static <E> java.lang.Iterable<E> collatedIterable​(java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b)
      Combines the two provided iterables into an ordered iterable using natural ordering.
      static <E> java.lang.Iterable<E> collatedIterable​(java.util.Comparator<? super E> comparator, java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b)
      Combines the two provided iterables into an ordered iterable using the provided comparator.
      static <E> boolean contains​(java.lang.Iterable<? extends E> iterable, E object, Equator<? super E> equator)
      Checks if the object is contained in the given iterable.
      static <E> boolean contains​(java.lang.Iterable<E> iterable, java.lang.Object object)
      Checks if the object is contained in the given iterable.
      static <E> long countMatches​(java.lang.Iterable<E> input, Predicate<? super E> predicate)
      Counts the number of elements in the input iterable that match the predicate.
      static <E> java.lang.Iterable<E> emptyIfNull​(java.lang.Iterable<E> iterable)
      Returns an immutable empty iterable if the argument is null, or the argument itself otherwise.
      static <E> java.lang.Iterable<E> emptyIterable()
      Gets an empty iterable.
      static <E> java.lang.Iterable<E> filteredIterable​(java.lang.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​(java.lang.Iterable<E> iterable, Predicate<? super E> predicate)
      Finds the first element in the given iterable which matches the given predicate.
      static <T> T first​(java.lang.Iterable<T> iterable)
      Shortcut for get(iterator, 0).
      static <E> void forEach​(java.lang.Iterable<E> iterable, Closure<? super E> closure)
      Applies the closure to each element of the provided iterable.
      static <E> E forEachButLast​(java.lang.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​(java.lang.Iterable<E> iterable, T obj)
      Returns the number of occurrences of the provided object in the iterable.
      static <T> T get​(java.lang.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​(java.lang.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​(java.lang.Iterable<?> iterable)
      Answers true if the provided iterable is empty.
      static <E> java.lang.Iterable<E> loopingIterable​(java.lang.Iterable<E> iterable)
      Returns a view of the given iterable which will cycle infinitely over its elements.
      static <E> boolean matchesAll​(java.lang.Iterable<E> iterable, Predicate<? super E> predicate)
      Answers true if a predicate is true for every element of an iterable.
      static <E> boolean matchesAny​(java.lang.Iterable<E> iterable, Predicate<? super E> predicate)
      Answers true if a predicate is true for any element of the iterable.
      static <O,​R extends java.util.Collection<O>>
      java.util.List<R>      		 partition​(java.lang.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> java.util.List<java.util.List<O>> partition​(java.lang.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> java.util.List<java.util.List<O>> partition​(java.lang.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> java.lang.Iterable<E> reversedIterable​(java.lang.Iterable<E> iterable)
      Returns a reversed view of the given iterable.
      static int size​(java.lang.Iterable<?> iterable)
      Returns the number of elements contained in the given iterator.
      static <E> java.lang.Iterable<E> skippingIterable​(java.lang.Iterable<E> iterable, long elementsToSkip)
      Returns a view of the given iterable that skips the first N elements.
      static <E> java.util.List<E> toList​(java.lang.Iterable<E> iterable)
      Gets a new list with the contents of the provided iterable.
      static <E> java.lang.String toString​(java.lang.Iterable<E> iterable)
      Returns a string representation of the elements of the specified iterable.
      static <E> java.lang.String toString​(java.lang.Iterable<E> iterable, Transformer<? super E,​java.lang.String> transformer)
      Returns a string representation of the elements of the specified iterable.
      static <E> java.lang.String toString​(java.lang.Iterable<E> iterable, Transformer<? super E,​java.lang.String> transformer, java.lang.String delimiter, java.lang.String prefix, java.lang.String suffix)
      Returns a string representation of the elements of the specified iterable.
      static <I,​O>
      java.lang.Iterable<O>      		 transformedIterable​(java.lang.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> java.lang.Iterable<E> uniqueIterable​(java.lang.Iterable<E> iterable)
      Returns a unique view of the given iterable.
      static <E> java.lang.Iterable<E> unmodifiableIterable​(java.lang.Iterable<E> iterable)
      Returns an unmodifiable view of the given iterable.
      static <E> java.lang.Iterable<E> zippingIterable​(java.lang.Iterable<? extends E> a, java.lang.Iterable<? extends E> b)
      Interleaves two iterables into a single iterable.
      static <E> java.lang.Iterable<E> zippingIterable​(java.lang.Iterable<? extends E> first, java.lang.Iterable<? extends E>... others)
      Interleaves two iterables into a single iterable.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • IterableUtils

        public IterableUtils()

    • Method Detail

      • emptyIterable

        public static <E> java.lang.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> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a,
                                                        java.lang.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:
        java.lang.NullPointerException - if either a or b is null

      • chainedIterable

        public static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a,
                                                        java.lang.Iterable<? extends E> b,
                                                        java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • chainedIterable

        public static <E> java.lang.Iterable<E> chainedIterable​(java.lang.Iterable<? extends E> a,
                                                        java.lang.Iterable<? extends E> b,
                                                        java.lang.Iterable<? extends E> c,
                                                        java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • chainedIterable

        public static <E> java.lang.Iterable<E> chainedIterable​(java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • collatedIterable

        public static <E> java.lang.Iterable<E> collatedIterable​(java.lang.Iterable<? extends E> a,
                                                         java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • collatedIterable

        public static <E> java.lang.Iterable<E> collatedIterable​(java.util.Comparator<? super E> comparator,
                                                         java.lang.Iterable<? extends E> a,
                                                         java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • filteredIterable

        public static <E> java.lang.Iterable<E> filteredIterable​(java.lang.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:
        java.lang.NullPointerException - if either iterable or predicate is null

      • boundedIterable

        public static <E> java.lang.Iterable<E> boundedIterable​(java.lang.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:
        java.lang.IllegalArgumentException - if maxSize is negative
        java.lang.NullPointerException - if iterable is null

      • loopingIterable

        public static <E> java.lang.Iterable<E> loopingIterable​(java.lang.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:
        java.lang.NullPointerException - if iterable is null

      • reversedIterable

        public static <E> java.lang.Iterable<E> reversedIterable​(java.lang.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:
        java.lang.NullPointerException - if iterable is null
        See Also:
        ReverseListIterator

      • skippingIterable

        public static <E> java.lang.Iterable<E> skippingIterable​(java.lang.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:
        java.lang.IllegalArgumentException - if elementsToSkip is negative
        java.lang.NullPointerException - if iterable is null

      • transformedIterable

        public static <I,​O> java.lang.Iterable<O> transformedIterable​(java.lang.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:
        java.lang.NullPointerException - if either iterable or transformer is null

      • uniqueIterable

        public static <E> java.lang.Iterable<E> uniqueIterable​(java.lang.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:
        java.lang.NullPointerException - if iterable is null

      • unmodifiableIterable

        public static <E> java.lang.Iterable<E> unmodifiableIterable​(java.lang.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:
        java.lang.NullPointerException - if iterable is null

      • zippingIterable

        public static <E> java.lang.Iterable<E> zippingIterable​(java.lang.Iterable<? extends E> a,
                                                        java.lang.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:
        java.lang.NullPointerException - if either a or b is null

      • zippingIterable

        public static <E> java.lang.Iterable<E> zippingIterable​(java.lang.Iterable<? extends E> first,
                                                        java.lang.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:
        java.lang.NullPointerException - if either of the provided iterables is null

      • emptyIfNull

        public static <E> java.lang.Iterable<E> emptyIfNull​(java.lang.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​(java.lang.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:
        java.lang.NullPointerException - if closure is null

      • forEachButLast

        public static <E> E forEachButLast​(java.lang.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​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • indexOf

        public static <E> int indexOf​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • matchesAll

        public static <E> boolean matchesAll​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • matchesAny

        public static <E> boolean matchesAny​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • countMatches

        public static <E> long countMatches​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • isEmpty

        public static boolean isEmpty​(java.lang.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​(java.lang.Iterable<E> iterable,
                                   java.lang.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​(java.lang.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:
        java.lang.NullPointerException - if equator is null

      • frequency

        public static <E,​T extends E> int frequency​(java.lang.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​(java.lang.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:
        java.lang.IndexOutOfBoundsException - if the index is invalid

      • first

        public static <T> T first​(java.lang.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:
        java.lang.IndexOutOfBoundsException - if the request is invalid
        Since:
        4.2

      • size

        public static int size​(java.lang.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> java.util.List<java.util.List<O>> partition​(java.lang.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:
        java.lang.NullPointerException - if predicate is null

      • partition

        public static <O> java.util.List<java.util.List<O>> partition​(java.lang.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:
        java.lang.NullPointerException - if any predicate is null

      • partition

        public static <O,​R extends java.util.Collection<O>> java.util.List<R> partition​(java.lang.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:
        java.lang.NullPointerException - if any predicate is null

      • toList

        public static <E> java.util.List<E> toList​(java.lang.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> java.lang.String toString​(java.lang.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> java.lang.String toString​(java.lang.Iterable<E> iterable,
                                            Transformer<? super E,​java.lang.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:
        java.lang.NullPointerException - if transformer is null

      • toString

        public static <E> java.lang.String toString​(java.lang.Iterable<E> iterable,
                                            Transformer<? super E,​java.lang.String> transformer,
                                            java.lang.String delimiter,
                                            java.lang.String prefix,
                                            java.lang.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:
        java.lang.NullPointerException - if either transformer, delimiter, prefix or suffix is null