Package: java.lang

## [Java] Interface Iterable

-     public interface Iterable

  GDK enhancements for Iterable.

  displayName:
    Iterable
  receiverFqcn:
    java.lang.Iterable

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public boolean` | `any(Closure predicate)` Iterates over the contents of an iterable, and checks whether a predicate is valid for at least one element.
    `<T>` | `public boolean` | `any(Predicate<? super T> predicate)` Iterates over the contents of an iterable, and checks whether a predicate is valid for at least one element.
    `<T, P>` | `public boolean` | `any(BiPredicate<? super T, ? super P> predicate, P param)` Iterates over the contents of an iterable, and checks whether the given predicate is valid for at least one element when called with that element and the supplied `param`.
    `<T>` | `public Collection<T>` | `asCollection()` Converts this Iterable to a Collection.
    `<T>` | `public List<T>` | `asList()` Converts this Iterable to a List.
    `<T>` | `public T` | `asType(Class<T> clazz)` Converts the given iterable to another type.
    `` | `public Object` | `average()` Averages the items in an Iterable.
    `<T>` | `public Object` | `average(Closure closure)` Averages the result of applying a closure to each item of an Iterable.
    `<T>` | `public BufferedIterator<T>` | `bufferedIterator()` Returns a `BufferedIterator` that allows examining the next element without consuming it.
    `<T>` | `public List<List<T>>` | `chop(int chopSizes)` Chops the Iterable into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public List<List<T>>` | `chop(boolean returnEarly, int chopSizes)` Chops the Iterable into pieces, returning lists with sizes corresponding to the supplied chop sizes.
    `<T>` | `public List<List<T>>` | `collate(int size)` Collates this iterable into sub-lists of length `size`.
    `<T>` | `public List<List<T>>` | `collate(int size, int step)` Collates this iterable into sub-lists of length `size` stepping through the code `step` elements for each subList.
    `<T>` | `public List<List<T>>` | `collate(int size, boolean keepRemainder)` Collates this iterable into sub-lists of length `size`.
    `<T>` | `public List<List<T>>` | `collate(int size, int step, boolean keepRemainder)` Collates this iterable into sub-lists of length `size` stepping through the code `step` elements for each sub-list.
    `<T>` | `public List<T>` | `collect()` Iterates through this collection transforming each entry into a new value using Closure.IDENTITY as a transformer, basically returning a list of items copied from the original collection.
    `<E, T>` | `public List<T>` | `collect(Closure<T> transform)` Iterates through this Iterable transforming each entry into a new value using the `transform` closure returning a list of transformed values.
    `<E, T>` | `public List<T>` | `collect(Function<? super E, ? extends T> transform)` Iterates through this Iterable transforming each item into a new value using the `transform` function, returning a list of transformed values.
    `<E, T, C extends java.util.Collection<T>>` | `public C` | `collect(C collector, Closure<? extends T> transform)` Iterates through this collection transforming each value into a new value using the `transform` closure and adding it to the supplied `collector`.
    `<E, T, C extends java.util.Collection<T>>` | `public C` | `collect(C collector, Function<? super E, ? extends T> transform)` Iterates through this Iterable transforming each value into a new value using the `transform` function and adding it to the supplied `collector`.
    `<E, P, R>` | `public List<R>` | `collect(BiFunction<? super E, ? super P, ? extends R> transform, P param)` Iterates through this Iterable transforming each value into a new value using the two-argument `transform` function, with the supplied `param` fixed as the second argument, returning a list of transformed values.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Closure<?> transform)` Iterates through this Iterable transforming each item using the `transform` closure and returning a map of the resulting transformed entries.
    `<K, V>` | `public Map<K, V>` | `collectEntries()` A variant of collectEntries for Iterable objects using the identity closure as the transform.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector, Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)` A variant of collectEntries for Iterables with separate functions for transforming the keys and values.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)` A variant of collectEntries for Iterables with separate functions for transforming the keys and values.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Function<? super E, ? extends Entry<K, V>> transform)` A "fat-free" variant of Iterable.collectEntries which transforms each element of the Iterable into a Map.Entry using the supplied function, returning a Map of the transformed entries.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector, Function<? super E, ? extends Entry<K, V>> transform)` A "fat-free" variant of Iterable.collectEntries which transforms each element of the Iterable into a Map.Entry using the supplied function, adding the transformed entries to the supplied collector map.
    `<K, V, E>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector, Closure<?> transform)` Iterates through this Iterable transforming each item using the closure as a transformer into a map entry, returning the supplied map with all the transformed entries added to it.
    `<K, V>` | `public Map<K, V>` | `collectEntries(Map<K, V> collector)` A variant of collectEntries for Iterables using the identity closure as the transform and a supplied map as the destination of transformed entries.
    `<T, E>` | `public List<T>` | `collectMany(Closure<? extends Collection<? extends T>> projection)` Projects each item from a source Iterable to a collection and concatenates (flattens) the resulting collections into a single list.
    `<T, E>` | `public List<T>` | `collectMany(Function<? super E, ? extends Collection<? extends T>> projection)` Projects each item from a source Iterable to a collection and concatenates (flattens) the resulting collections into a single list.
    `<T, E>` | `public List<T>` | `collectMany()` Flattens an iterable of collections into a list.
    `<T, E, C extends java.util.Collection<T>>` | `public C` | `collectMany(C collector, Closure<? extends Collection<? extends T>> projection)` Projects each item from a source collection to a result collection and concatenates (flattens) the resulting collections adding them into the `collector`.
    `<T, E, C extends java.util.Collection<T>>` | `public C` | `collectMany(C collector, Function<? super E, ? extends Collection<? extends T>> projection)` Projects each item from a source collection to a result collection and concatenates (flattens) the resulting collections adding them into the `collector`.
    `` | `public List` | `collectNested(Closure transform)` Recursively iterates through this Iterable transforming each non-Collection value into a new value using the closure as a transformer.
    `<C extends java.util.Collection>` | `public C` | `collectNested(C collector, Closure transform)` Recursively iterates through this Iterable transforming each non-Collection value into a new value using the `transform` closure.
    `` | `public List<List>` | `combinations()` Finds all combinations of items from the given aggregate of collections.
    `<T>` | `public List<T>` | `combinations(Closure<T> function)` Finds all combinations of items from the given aggregate of collections, then returns the results of the supplied transform.
    `` | `public boolean` | `contains(Object item)` Returns `true` if this iterable contains the item.
    `` | `public boolean` | `containsAll(Object[] items)` Returns `true` if this iterable contains all the elements in the specified array.
    `` | `public Number` | `count(Object value)` Counts the number of occurrences of the given value inside this Iterable.
    `<T>` | `public Number` | `count(Closure closure)` Counts the number of occurrences which satisfy the given closure from inside this Iterable.
    `<T>` | `public Number` | `count(Predicate<? super T> predicate)` Counts the number of occurrences which satisfy the given predicate from inside this Iterable.
    `<T, P>` | `public Number` | `count(BiPredicate<? super T, ? super P> predicate, P param)` Counts the number of occurrences which satisfy the given two-argument condition, with the supplied `param` fixed as the second argument.
    `<T, E extends java.lang.Number>` | `public E` | `count(E initialCount, Closure closure)` Counts the number of occurrences which satisfy the given closure from inside this Iterable.
    `<K, E>` | `public Map<K, Integer>` | `countBy(Closure<K> closure)` Sorts all collection members into groups determined by the supplied mapping closure and counts the group size.
    `<K, E>` | `public Map<K, Integer>` | `countBy(Function<? super E, ? extends K> function)` Sorts all collection members into groups determined by the supplied mapping function and counts the group size.
    `<E>` | `public Map<E, Integer>` | `countBy()` Creates a multiset-like map of the collection members.
    `` | `public boolean` | `disjoint(Iterable right)` Returns `true` if the intersection of two iterables is empty.
    `<T>` | `public Collection<T>` | `drop(int num)` Drops the given number of elements from the head of this Iterable.
    `<T>` | `public Collection<T>` | `dropRight(int num)` Drops the given number of elements from the tail of this Iterable.
    `<T>` | `public Collection<T>` | `dropWhile(Closure condition)` Returns a suffix of this Iterable where elements are dropped from the front while the given closure evaluates to true.
    `<T>` | `public Collection<T>` | `dropWhile(Predicate<? super T> condition)` Returns a suffix of an Iterable where elements are dropped from the front while the predicate is satisfied.
    `<T>` | `public Iterable<T>` | `each(Closure closure)` Iterates through an Iterable, passing each item to the given closure.
    `<T>` | `public Iterable<T>` | `each(Consumer<? super T> consumer)` Iterates through an Iterable, passing each item to the given consumer.
    `` | `public void` | `eachCombination(Closure<?> function)` Applies a function on each combination of the input lists.
    `<T>` | `public Iterator<List<T>>` | `eachPermutation(Closure closure)` Iterates over all permutations of a collection, running a closure for each iteration.
    `<T>` | `public Iterable<T>` | `eachWithIndex(Closure closure)` Iterates through an iterable type, passing each item and the item's index (a counter starting at zero) to the given closure.
    `<T>` | `public Iterable<T>` | `eachWithIndex(ObjIntConsumer<? super T> consumer)` Iterates through an Iterable, passing each item and the item's index (a counter starting at zero) to the given consumer.
    `<T>` | `public boolean` | `every(Closure predicate)` Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this iterable).
    `<T>` | `public boolean` | `every(Predicate<? super T> predicate)` Used to determine if the given predicate is valid (i.e. returns `true` for all items in this iterable).
    `<T, P>` | `public boolean` | `every(BiPredicate<? super T, ? super P> predicate, P param)` Used to determine if the given predicate is valid (i.e. returns `true` for all items in this iterable) when called with each element and the supplied `param`.
    `<T>` | `public T` | `find(Predicate<? super T> condition)` Finds the first value matching the given predicate.
    `<T, P>` | `public T` | `find(BiPredicate<? super T, ? super P> condition, P param)` Finds the first value matching the given two-argument condition, with the supplied `param` fixed as the second argument.
    `<T>` | `public List<T>` | `findAll(Predicate<? super T> condition)` Finds all values matching the given predicate.
    `<T, P>` | `public List<T>` | `findAll(BiPredicate<? super T, ? super P> condition, P param)` Finds all values matching the given two-argument condition, with the supplied `param` fixed as the second argument.
    `<T>` | `public int` | `findIndexOf(Closure condition)` Iterates over the elements of an Iterable and returns the index of the first item that satisfies the condition specified by the closure.
    `<T>` | `public int` | `findIndexOf(int startIndex, Closure condition)` Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index of the first item that satisfies the condition specified by the closure.
    `<T>` | `public List<Number>` | `findIndexValues(Closure condition)` Iterates over the elements of an Iterable and returns the index values of the items that match the condition specified in the closure.
    `<T>` | `public List<Number>` | `findIndexValues(Number startIndex, Closure condition)` Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index values of the items that match the condition specified in the closure.
    `<T>` | `public int` | `findLastIndexOf(Closure condition)` Iterates over the elements of an Iterable and returns the index of the last item that matches the condition specified in the closure.
    `<T>` | `public int` | `findLastIndexOf(int startIndex, Closure condition)` Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.
    `<S, T, U extends T, V extends T>` | `public T` | `findResult(U defaultResult, Closure<V> condition)` Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result.
    `<T, U extends T, V extends T>` | `public T` | `findResult(V defaultResult)` Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result.
    `<T, U>` | `public T` | `findResult(Closure<T> condition)` Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result.
    `<T>` | `public T` | `findResult()` Iterates through the Iterable stopping once the first non-null result is found and returning that result.
    `<T, U>` | `public Collection<T>` | `findResults(Closure<T> filteringTransform)` Iterates through the Iterable transforming items using the supplied closure and collecting any non-null results.
    `<T>` | `public Collection<T>` | `findResults()` Iterates through the Iterable collecting any non-null results.
    `<T>` | `public T` | `first()` Returns the first item from the Iterable.
    `<T, E>` | `public Collection<T>` | `flatten()` Flatten an Iterable.
    `<T, E>` | `public Collection<T>` | `flatten(boolean flattenOptionals)` Flatten an Iterable.
    `<T, E>` | `public Collection<T>` | `flatten(Closure<?> flattenUsing)` Flatten an Iterable.
    `<T, E>` | `public Collection<T>` | `flatten(boolean flattenOptionals, Closure<?> flattenUsing)` Flatten an Iterable.
    `<T>` | `public Collection<T>` | `flattenMany(Closure<?> transform)` Flatten an Iterable.
    `<T>` | `public T` | `getAt(int idx)` Support the subscript operator for an Iterable.
    `<K, T>` | `public Map<K, List<T>>` | `groupBy(Closure<K> closure)` Sorts all Iterable members into groups determined by the supplied mapping closure.
    `<K, T>` | `public Map<K, List<T>>` | `groupBy(Function<? super T, ? extends K> function)` Sorts all Iterable members into groups determined by the supplied mapping function.
    `` | `public Map` | `groupBy(Object closures)` Sorts all Iterable members into (sub)groups determined by the supplied mapping closures.
    `` | `public Map` | `groupBy(List<Closure> closures)` Sorts all Iterable members into (sub)groups determined by the supplied mapping closures.
    `<T, K>` | `public Map<K, List<T>>` | `groupByMany(Function<? super T, ? extends Iterable<? extends K>> keyFn)` Groups all items from the iterable into (sub)groups determined by the supplied key mapping closure.
    `<T, U, K>` | `public Map<K, List<U>>` | `groupByMany(Function<? super T, ? extends U> valueFn, Function<? super T, ? extends Iterable<? extends K>> keyFn)` Groups all elements from the iterable into (sub)groups determined by the supplied key mapping closure.
    `<T>` | `public List<List<T>>` | `groupConsecutive()` Splits this Iterable into a list of sublists, each a maximal run of adjacent elements considered equal.
    `<T, K>` | `public List<List<T>>` | `groupConsecutive(Function<? super T, ? extends K> keyFn)` Splits this Iterable into runs of adjacent elements whose key, as computed by the given function, is equal (number-aware coercion).
    `<T>` | `public List<List<T>>` | `groupConsecutive(BiPredicate<? super T, ? super T> sameRun)` Splits this Iterable into runs where the given predicate, applied to the current run's previous element and the next element, holds.
    `<T>` | `public T` | `head()` Returns the first item from the Iterable.
    `<E>` | `public Map<Integer, E>` | `indexed()` Zips an Iterable with indices in (index, value) order.
    `<E>` | `public Map<Integer, E>` | `indexed(int offset)` Zips an Iterable with indices in (index, value) order.
    `<T>` | `public Collection<T>` | `init()` Returns the items from the Iterable excluding the last item.
    `<T>` | `public List<List<T>>` | `inits()` Calculates the init values of this Iterable: the first value will be this list of all items from the iterable and the final one will be an empty list, with the intervening values the results of successive applications of init on the items.
    `<E extends T, T, V extends T>` | `public T` | `inject(Closure<V> closure)` Iterates through the given object, passing the first two elements to the closure.
    `<T>` | `public T` | `inject(BinaryOperator<T> operator)` Iterates through the given iterable, passing the first two elements to the operator.
    `<E, T, U extends T, V extends T>` | `public T` | `inject(U initialValue, Closure<V> closure)` Iterates through the given object, passing in the initial value to the 2-arg closure along with the first item.
    `<E, U>` | `public U` | `inject(U initialValue, BiFunction<? super U, ? super E, ? extends U> function)` Iterates through the given iterable, passing in the initial value to the function along with the first item.
    `<E, T, U extends T, V extends T>` | `public List<T>` | `injectAll(U initialValue, Closure<V> closure)` Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<E, U>` | `public List<U>` | `injectAll(U initialValue, BiFunction<? super U, ? super E, ? extends U> function)` Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<E extends T, T, V extends T>` | `public List<T>` | `injectAll(Closure<V> closure)` Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<T>` | `public List<T>` | `injectAll(BinaryOperator<T> operator)` Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.
    `<T, U extends T, V extends T>` | `public List<T>` | `interleave(Iterable<V> other)` The elements from two Iterables interleaved.
    `<T, U extends T, V extends T>` | `public List<T>` | `interleave(Iterable<V> other, boolean includeRemainder)` The elements from two Iterables interleaved.
    `<T>` | `public Collection<T>` | `intersect(Iterable<T> right)` Create a Collection composed of the intersection of both iterables.
    `<T>` | `public Collection<T>` | `intersect(Iterable<T> right, Comparator<? super T> comparator)` Create a Collection composed of the intersection of both iterables.
    `<T>` | `public Collection<T>` | `intersect(Iterable<T> right, Closure condition)` Create a Collection composed of the intersection of both iterables.
    `` | `public boolean` | `isCase(Object switchValue)` Special 'case' implementation for iterables which tests if the 'switch' operand is contained in any of the 'case' values.
    `` | `public boolean` | `isEmpty()` Check whether an `Iterable` has elements
         def items = [1]
         def iterable = { [ hasNext:{ !
    `<T>` | `public boolean` | `isSorted()` Determines if the Iterable is sorted.
    `<T>` | `public boolean` | `isSorted(Comparator<? super T> comparator)` Determines if the Iterable is sorted according to the given Comparator.
    `<T>` | `public boolean` | `isSorted(Function<? super T, ?> keyExtractor)` Determines if the Iterable is sorted in non-descending order of the keys returned by the given key extractor.
    `` | `public String` | `join()` Concatenates the `toString()` representation of each item from the Iterable.
    `` | `public String` | `join(String separator)` Concatenates the `toString()` representation of each item from the Iterable, with the given String as a separator between each item.
    `<T>` | `public T` | `last()` Returns the last item from the Iterable.
    `<T>` | `public T` | `max()` Adds max() method to Iterable objects.
    `<T>` | `public T` | `max(Comparator<? super T> comparator)` Selects the maximum value found in the Iterable using the given comparator.
    `<T>` | `public T` | `max(Closure closure)` Selects the item in the iterable which when passed as a parameter to the supplied closure returns the maximum value.
    `<T>` | `public T` | `min()` Adds min() method to Collection objects.
    `<T>` | `public T` | `min(Comparator<? super T> comparator)` Selects the minimum value found in the Iterable using the given comparator.
    `<T>` | `public T` | `min(Closure closure)` Selects the item in the iterable which when passed as a parameter to the supplied closure returns the minimum value.
    `<T>` | `public Collection<T>` | `minus(Iterable<?> removeMe)` Create a new Collection composed of the elements of the first Iterable minus every occurrence of elements of the given Iterable.
    `<T>` | `public Collection<T>` | `minus(Iterable<?> removeMe, Closure condition)` Create a new Collection composed of the elements of the first Iterable minus every matching occurrence as determined by the condition closure of elements of the given Iterable.
    `<T>` | `public Collection<T>` | `minus(Iterable<?> removeMe, Comparator<? super T> comparator)` Create a new Collection composed of the elements of the first Iterable minus every matching occurrence as determined by the condition comparator of elements of the given Iterable.
    `<T>` | `public Collection<T>` | `minus(Object removeMe)` Create a new Collection composed of the elements of the first Iterable minus every occurrence of the given element to remove.
    `<T>` | `public Collection<T>` | `multiply(Number factor)` Create a Collection composed of the elements of this Iterable, repeated a certain number of times.
    `<T>` | `public Set<List<T>>` | `permutations()` Finds all permutations of an iterable.
    `<T, V>` | `public List<V>` | `permutations(Closure<V> function)` Finds all permutations of an iterable, applies a function to each permutation and collects the result into a list.
    `<T>` | `public Collection<T>` | `plus(Iterable<T> right)` Create a Collection as a union of two iterables.
    `<T>` | `public Collection<T>` | `plus(T right)` Create a collection as a union of an Iterable and an Object.
    `<T>` | `public Collection<T>` | `repeat(int count)` Repeat the elements from an iterable.
    `<T>` | `public Iterator<T>` | `repeat()` Repeat the elements from an iterable infinitely.
    `` | `public int` | `size()` Provide the standard Groovy `size()` method for `Iterable`.
    `<T>` | `public List<T>` | `sort()` Sorts the Collection.
    `<T>` | `public List<T>` | `sort(boolean mutate)` Sorts the Iterable.
    `<T>` | `public List<T>` | `sort(boolean mutate, Comparator<? super T> comparator)` Sorts the Iterable using the given Comparator.
    `<T>` | `public List<T>` | `sort(Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `<T>` | `public List<T>` | `sort(boolean mutate, Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `<T>` | `public Stream<T>` | `stream()` Returns a sequential Stream with the specified element(s) as its source.
    `` | `public Object` | `sum()` Sums the items in an Iterable.
    `` | `public Object` | `sum(Object initialValue)` Sums the items in an Iterable, adding the result to some initial value.
    `<T>` | `public Object` | `sum(Closure closure)` Sums the result of applying a closure to each item of an Iterable.
    `<T>` | `public Object` | `sum(Object initialValue, Closure closure)` Sums the result of applying a closure to each item of an Iterable to some initial value.
    `<T>` | `public Collection<T>` | `tail()` Returns the items from the Iterable excluding the first item.
    `<T>` | `public List<List<T>>` | `tails()` Calculates the tail values of this Iterable: the first value will be this list of all items from the iterable and the final one will be an empty list, with the intervening values the results of successive applications of tail on the items.
    `<T>` | `public Collection<T>` | `take(int num)` Returns the first `num` elements from the head of this Iterable.
    `<T>` | `public Collection<T>` | `takeRight(int num)` Returns the last `num` elements from the tail of this Iterable.
    `<T>` | `public Collection<T>` | `takeWhile(Closure condition)` Returns a Collection containing the longest prefix of the elements from this Iterable where each element passed to the given closure evaluates to true.
    `<T>` | `public Collection<T>` | `takeWhile(Predicate<? super T> condition)` Returns the longest prefix of an Iterable where each element passes the given predicate.
    `<T>` | `public List<T>` | `toImmutableList()` Convert an Iterable to an immutable List.
    `<T>` | `public Set<T>` | `toImmutableSet()` Convert an Iterable to an immutable Set.
    `<T>` | `public List<T>` | `toList()` Convert an Iterable to a List.
    `<T>` | `public Set<T>` | `toSet()` Convert an Iterable to a Set.
    `<T>` | `public List<T>` | `toSorted()` Sorts the Iterable.
    `<T>` | `public List<T>` | `toSorted(Comparator<? super T> comparator)` Sorts the Iterable using the given Comparator.
    `<T>` | `public List<T>` | `toSorted(Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `` | `public SpreadMap` | `toSpreadMap()` Creates a spreadable map from this iterable.
    `<T>` | `public Collection<T>` | `toUnique(Comparator<? super T> comparator)` Returns a Collection containing the items from the Iterable but with duplicates removed.
    `<T>` | `public Collection<T>` | `toUnique()` Returns a Collection containing the items from the Iterable but with duplicates removed using the natural ordering of the items to determine uniqueness.
    `<T>` | `public Collection<T>` | `toUnique(Closure condition)` Returns a Collection containing the items from the Iterable but with duplicates removed.
    `<T>` | `public Collection<T>` | `union(Iterable<T> right)` Create a Collection composed of the union of both iterables.
    `<T>` | `public Collection<T>` | `union(Iterable<T> right, Comparator<? super T> comparator)` Create a Collection composed of the union of both iterables.
    `<T>` | `public Collection<T>` | `union(Iterable<T> right, Closure condition)` Create a Collection composed of the union of both iterables.
    `<K, V>` | `public Map<K, V>` | `withCollectedKeys(Map<K, V> collector, Function<? super V, K> keyTransform)` Transform Iterable elements into Map entries with values unchanged and keys transformed using the supplied function.
    `<K, V>` | `public Map<K, V>` | `withCollectedKeys(Function<? super V, K> keyTransform)` Transform Iterable elements into Map entries with values unchanged and keys transformed using the supplied function.
    `<K, V>` | `public Map<K, V>` | `withCollectedValues(Map<K, V> collector, Function<? super K, V> valueTransform)` Transform Iterable elements into Map entries with keys unchanged and values transformed using the supplied function.
    `<K, V>` | `public Map<K, V>` | `withCollectedValues(Function<? super K, V> valueTransform)` Transform Iterable elements into Map entries with keys unchanged and values transformed using the supplied function.
    `<E>` | `public List<Tuple2<E, Integer>>` | `withIndex()` Zips an Iterable with indices in (value, index) order.
    `<E>` | `public List<Tuple2<E, Integer>>` | `withIndex(int offset)` Zips an Iterable with indices in (value, index) order.
    `<U, V>` | `public List<Tuple2<U, V>>` | `zip(Iterable<V> other)` A list of all the pairs from two Iterables.
    `<U, V>` | `public Collection<Tuple2<U, V>>` | `zipAll(Iterable<V> other, U selfDefault, V otherDefault)` A collection of all the pairs of two Iterables of potentially different size.
    `<T>` | `public List<Tuple2<T, T>>` | `zipWithNext()` Returns a list of all the successive adjacent pairs from this Iterable (a sliding window of size 2, step 1).
    `<T, R>` | `public List<R>` | `zipWithNext(BiFunction<? super T, ? super T, ? extends R> combiner)` Applies the combiner to each successive adjacent pair from this Iterable, returning the list of results.

- - ### Method Detail

    - #### <T> public boolean any(Closure predicate)

      Iterates over the contents of an iterable, and checks whether a predicate is valid for at least one element.

           assert [1, 2, 3].any { it == 2 }
           assert ![1, 2, 3].any { it > 3 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if any iteration for the object matches the closure predicate
      Since:
        1.0

    - #### <T> public boolean any(Predicate<? super T> predicate)

      Iterates over the contents of an iterable, and checks whether a predicate is valid for at least one element. A "fat-free" variant of Iterable.any accepting a Predicate.

           import java.util.function.Predicate
           Predicate<Integer> isEven = n -> n % 2 == 0
           assert [1, 2, 3].any(isEven)
           assert ![1, 3, 5].any(isEven)

      Parameters:
        `predicate` - the predicate used for matching
      Returns:
        true if any element of the iterable matches the predicate
      Since:
        6.0.0

    - #### <T, P> public boolean any(BiPredicate<? super T, ? super P> predicate, P param)

      Iterates over the contents of an iterable, and checks whether the given predicate is valid for at least one element when called with that element and the supplied `param`. A "fat-free" variant of Iterable.any accepting a BiPredicate together with an additional argument, mirroring Iterable.find.

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert [1, 2, 3].any(divisibleBy, 2)
           assert ![1, 3, 5].any(divisibleBy, 2)

      Parameters:
        `predicate` - the predicate used for matching
        `param` - the additional argument passed to the predicate
      Returns:
        true if any element of the iterable matches the predicate
      Since:
        6.0.0

    - #### <T> public Collection<T> asCollection()

      Converts this Iterable to a Collection. Returns the original argument if it is already a Collection.

      Example usage:

           assert new HashSet().asCollection() instanceof Collection

      Returns:
        a newly created List if this Iterable is not already a Collection
      Since:
        2.4.0

    - #### <T> public List<T> asList()

      Converts this Iterable to a List. Returns the original Iterable if it is already a List.

      Example usage:

           assert new HashSet().asList() instanceof List

      Returns:
        a newly created List if this Iterable is not already a List
      Since:
        2.2.0

    - #### <T> public T asType(Class<T> clazz)

      Converts the given iterable to another type.

      Parameters:
        `clazz` - the desired class
      Returns:
        the object resulting from this type conversion
      See Also:
        asType(Collection, Class)
      Since:
        2.4.12

    - #### public Object average()

      Averages the items in an Iterable. This is equivalent to invoking the "plus" method on all items in the Iterable and then dividing by the total count using the "div" method for the resulting sum.

           assert 3 == [1, 2, 6].average()

      Returns:
        The average of all the items
      See Also:
        average(Iterator)
      Since:
        3.0.0

    - #### <T> public Object average(Closure closure)

      Averages the result of applying a closure to each item of an Iterable. `iter.average(closure)` is equivalent to: `iter.collect(closure).average()`.

      Example:

           assert 20 == [1, 3].average { it * 10 }
           assert 3 == ['to', 'from'].average { it.size() }

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
      Returns:
        The average of the values returned by applying the closure to each item of the Iterable.
      Since:
        3.0.0

    - #### <T> public BufferedIterator<T> bufferedIterator()

      Returns a `BufferedIterator` that allows examining the next element without consuming it.

           assert new LinkedHashSet([1,2,3,4]).bufferedIterator().with { [head(), toList()] } == [1, [1,2,3,4]]

      Returns:
        a BufferedIterator for traversing self
      Since:
        2.5.0

    - #### <T> public List<List<T>> chop(int chopSizes)

      Chops the Iterable into pieces, returning lists with sizes corresponding to the supplied chop sizes. Using a chop size of -1 will cause that piece to contain all remaining items from the Iterable.

      Example usage:

           assert [1, 2, 3, 4].chop(1) == [[1]]
           assert [1, 2, 3, 4].chop(1,-1) == [[1], [2, 3, 4]]
           assert ('a'..'h').chop(2, 4) == [['a', 'b'], ['c', 'd', 'e', 'f']]
           assert ['a', 'b', 'c', 'd', 'e'].chop(3) == [['a', 'b', 'c']]
           assert ['a', 'b', 'c', 'd', 'e'].chop(1, 2, 3) == [['a'], ['b', 'c'], ['d', 'e']]
           assert ['a', 'b', 'c', 'd', 'e'].chop(1, 2, 3, 3, 3) == [['a'], ['b', 'c'], ['d', 'e']]

      Parameters:
        `chopSizes` - the sizes for the returned pieces
      Returns:
        a list of lists chopping the original iterable into pieces determined by chopSizes
      See Also:
        to chop an Iterable into pieces of a fixed size
      Since:
        2.5.2

    - #### <T> public List<List<T>> chop(boolean returnEarly, int chopSizes)

      Chops the Iterable into pieces, returning lists with sizes corresponding to the supplied chop sizes. When no more elements remain in the iterable, truncated (possibly empty) pieces are returned unless returnEarly is true. Using a chop size of -1 will cause that piece to contain all remaining items from the Iterable.

      Example usage:

           assert ['a', 'b', 'c', 'd', 'e'].chop(false, 1, 2, 3, 3, 3) == [['a'], ['b', 'c'], ['d', 'e'], [], []]
           assert ['a', 'b', 'c', 'd', 'e'].chop(true, 1, 2, 3, 3, 3) == [['a'], ['b', 'c'], ['d', 'e']]

      Parameters:
        `chopSizes` - the sizes for the returned pieces
        `returnEarly` - as soon as the source is exhausted, ignore remaining asked for chop sizes
      Returns:
        a list of lists chopping the original iterable into pieces determined by chopSizes
      See Also:
        to chop an Iterable into pieces of a fixed size
      Since:
        2.5.2

    - #### <T> public List<List<T>> collate(int size)

      Collates this iterable into sub-lists of length `size`. Example:

          def list = [ 1, 2, 3, 4, 5, 6, 7 ]
           def coll = list.collate( 3 )
           assert coll == [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7 ] ]

      Parameters:
        `size` - the length of each sub-list in the returned list
      Returns:
        a List containing the data collated into sub-lists
      Since:
        2.4.0

    - #### <T> public List<List<T>> collate(int size, int step)

      Collates this iterable into sub-lists of length `size` stepping through the code `step` elements for each subList. Example:

          def list = [ 1, 2, 3, 4 ]
           def coll = list.collate( 3, 1 )
           assert coll == [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4 ], [ 4 ] ]

      Parameters:
        `size` - the length of each sub-list in the returned list
        `step` - the number of elements to step through for each sub-list
      Returns:
        a List containing the data collated into sub-lists
      Since:
        2.4.0

    - #### <T> public List<List<T>> collate(int size, boolean keepRemainder)

      Collates this iterable into sub-lists of length `size`. Any remaining elements in the iterable after the subdivision will be dropped if `keepRemainder` is false. Example:

          def list = [ 1, 2, 3, 4, 5, 6, 7 ]
           def coll = list.collate( 3, false )
           assert coll == [ [ 1, 2, 3 ], [ 4, 5, 6 ] ]

      Parameters:
        `size` - the length of each sub-list in the returned list
        `keepRemainder` - if true, any remaining elements are returned as sub-lists. Otherwise they are discarded
      Returns:
        a List containing the data collated into sub-lists
      Since:
        2.4.0

    - #### <T> public List<List<T>> collate(int size, int step, boolean keepRemainder)

      Collates this iterable into sub-lists of length `size` stepping through the code `step` elements for each sub-list. Any remaining elements in the iterable after the subdivision will be dropped if `keepRemainder` is false.

      Example:

           def list = [ 1, 2, 3, 4 ]
           assert list.collate( 2, 2, true  ) == [ [ 1, 2 ], [ 3, 4 ] ]
           assert list.collate( 3, 1, true  ) == [ [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4 ], [ 4 ] ]
           assert list.collate( 3, 1, false ) == [ [ 1, 2, 3 ], [ 2, 3, 4 ] ]

      throws:
        IllegalArgumentException if the step is zero.
      Parameters:
        `size` - the length of each sub-list in the returned list
        `step` - the number of elements to step through for each sub-list
        `keepRemainder` - if true, any remaining elements are returned as sub-lists. Otherwise they are discarded
      Returns:
        a List containing the data collated into sub-lists
      Since:
        2.4.0

    - #### <T> public List<T> collect()

      Iterates through this collection transforming each entry into a new value using Closure.IDENTITY as a transformer, basically returning a list of items copied from the original collection.

          assert [1,2,3].collect() == [1,2,3]

      Returns:
        a List of the transformed values
      See Also:
        Closure.IDENTITY
      Since:
        2.5.0

    - #### <E, T> public List<T> collect(Closure<T> transform)

      Iterates through this Iterable transforming each entry into a new value using the `transform` closure returning a list of transformed values.

          assert [1,2,3].collect { it * 2 } == [2,4,6]

      Parameters:
        `transform` - the closure used to transform each item of the collection
      Returns:
        a List of the transformed values
      Since:
        2.5.0

    - #### <E, T> public List<T> collect(Function<? super E, ? extends T> transform)

      Iterates through this Iterable transforming each item into a new value using the `transform` function, returning a list of transformed values. A "fat-free" variant of Iterable.collect accepting a Function.

          assert [1, 2, 3].collect(n -> n * 2) == [2, 4, 6]

      Parameters:
        `transform` - the function used to transform each item of the Iterable
      Returns:
        a List of the transformed values
      Since:
        6.0.0

    - #### <E, T, C extends java.util.Collection<T>> public C collect(C collector, Closure<? extends T> transform)

      Iterates through this collection transforming each value into a new value using the `transform` closure and adding it to the supplied `collector`.

          assert [2,4,5,6].collect(new HashSet()) { (int)(it / 2) } == [1,2,3] as Set

      Parameters:
        `collector` - the Collection to which the transformed values are added
        `transform` - the closure used to transform each item
      Returns:
        the collector with all transformed values added to it
      Since:
        2.5.0

    - #### <E, T, C extends java.util.Collection<T>> public C collect(C collector, Function<? super E, ? extends T> transform)

      Iterates through this Iterable transforming each value into a new value using the `transform` function and adding it to the supplied `collector`. A "fat-free" variant of Iterable.collect accepting a Function.

          assert [2, 4, 5, 6].collect(new HashSet(), n -> (int)(n / 2)) == [1, 2, 3] as Set

      Parameters:
        `collector` - the Collection to which the transformed values are added
        `transform` - the function used to transform each item
      Returns:
        the collector with all transformed values added to it
      Since:
        6.0.0

    - #### <E, P, R> public List<R> collect(BiFunction<? super E, ? super P, ? extends R> transform, P param)

      Iterates through this Iterable transforming each value into a new value using the two-argument `transform` function, with the supplied `param` fixed as the second argument, returning a list of transformed values. This is a "fat-free" variant combining Iterable.collect with the right-currying performed by Lambdas.curryWith, so that `list.collect(transform, param)` is equivalent to `list.collect(curryWith(transform, param))`.

           import java.util.function.BiFunction
           BiFunction<String, Integer, String> repeat = (s, n) -> s * n
           assert ['a', 'b', 'c'].collect(repeat, 3) == ['aaa', 'bbb', 'ccc']

      Parameters:
        `transform` - a two-argument function used to transform each item
        `param` - the value to fix as the function's second argument
      Returns:
        a List of the transformed values
      Since:
        6.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Closure<?> transform)

      Iterates through this Iterable transforming each item using the `transform` closure and returning a map of the resulting transformed entries.

           def letters = "abc"
           // collect letters with index using list style
           assert (0..2).collectEntries { index -> [index, letters[index]] } == [0:'a', 1:'b', 2:'c']
           // collect letters with index using map style
           assert (0..2).collectEntries { index -> [(index): letters[index]] } == [0:'a', 1:'b', 2:'c']

      Note: When using the list-style of result, the behavior is '`def (key, value) = listResultFromClosure`'. While we strongly discourage using a list of size other than 2, Groovy's normal semantics apply in this case; throwing away elements after the second one and using null for the key or value for the case of a shortened list.
      Parameters:
        `transform` - the closure used for transforming, which has an item from self as the parameter and should return a Map.Entry, a Map or a two-element list containing the resulting key and value
      Returns:
        a Map of the transformed entries
      See Also:
        collectEntries(Iterator, Closure)
      Since:
        1.8.7

    - #### <K, V> public Map<K, V> collectEntries()

      A variant of collectEntries for Iterable objects using the identity closure as the transform. The source Iterable should contain a list of `[key, value]` tuples or `Map.Entry` objects.

           def nums = [1, 10, 100, 1000]
           def tuples = nums.collect{ [it, it.toString().size()] }
           assert tuples == [[1, 1], [10, 2], [100, 3], [1000, 4]]
           def map = tuples.collectEntries()
           assert map == [1:1, 10:2, 100:3, 1000:4]

      Returns:
        a Map of the transformed entries
      See Also:
        collectEntries(Iterator)
      Since:
        1.8.7

    - #### <K, V, E> public Map<K, V> collectEntries(Map<K, V> collector, Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)

      A variant of collectEntries for Iterables with separate functions for transforming the keys and values. The supplied collector map is used as the destination for transformed entries.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           assert languages.collectEntries([clojure:7], String::toLowerCase, String::size) == [clojure:7, groovy:6, java:4, kotlin:6, scala:5]

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `keyTransform` - a function for transforming Iterable elements into keys
        `valueTransform` - a function for transforming Iterable elements into values
      Returns:
        the collector with all transformed values added to it
      Since:
        5.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Function<? super E, K> keyTransform, Function<? super E, V> valueTransform)

      A variant of collectEntries for Iterables with separate functions for transforming the keys and values.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           assert languages.collectEntries(String::toLowerCase, String::size) ==
               [groovy:6, java:4, kotlin:6, scala:5]

      Parameters:
        `keyTransform` - a function for transforming Iterable elements into keys
        `valueTransform` - a function for transforming Iterable elements into values
      Returns:
        a Map of the transformed entries
      Since:
        5.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Function<? super E, ? extends Entry<K, V>> transform)

      A "fat-free" variant of Iterable.collectEntries which transforms each element of the Iterable into a Map.Entry using the supplied function, returning a Map of the transformed entries.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           assert languages.collectEntries(s -> Map.entry(s.toLowerCase(), s.size())) ==
               [groovy: 6, java: 4, kotlin: 6, scala: 5]

      Parameters:
        `transform` - a function for transforming Iterable elements into a Map.Entry
      Returns:
        a Map of the transformed entries
      Since:
        6.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Map<K, V> collector, Function<? super E, ? extends Entry<K, V>> transform)

      A "fat-free" variant of Iterable.collectEntries which transforms each element of the Iterable into a Map.Entry using the supplied function, adding the transformed entries to the supplied collector map. A `null` entry inserts nothing.

           def languages = ['Java', 'Kotlin']
           assert languages.collectEntries([groovy: 6], s -> Map.entry(s.toLowerCase(), s.size())) ==
               [groovy: 6, java: 4, kotlin: 6]

      Parameters:
        `collector` - the Map into which the transformed entries are put
        `transform` - a function for transforming Iterable elements into a Map.Entry
      Returns:
        the collector with all transformed entries added to it
      Since:
        6.0.0

    - #### <K, V, E> public Map<K, V> collectEntries(Map<K, V> collector, Closure<?> transform)

      Iterates through this Iterable transforming each item using the closure as a transformer into a map entry, returning the supplied map with all the transformed entries added to it.

           def letters = "abc"
           // collect letters with index
           assert (0..2).collectEntries( [:] ) { index -> [index, letters[index]] } == [0:'a', 1:'b', 2:'c']
           assert (0..2).collectEntries( [4:'d'] ) { index -> [(index+1): letters[index]] } == [1:'a', 2:'b', 3:'c', 4:'d']

      Note: When using the list-style of result, the behavior is '`def (key, value) = listResultFromClosure`'. While we strongly discourage using a list of size other than 2, Groovy's normal semantics apply in this case; throwing away elements after the second one and using null for the key or value for the case of a shortened list. If your collector Map doesn't support null keys or values, you might get a runtime error, e.g. NullPointerException or IllegalArgumentException.
      Parameters:
        `collector` - the Map into which the transformed entries are put
        `transform` - the closure used for transforming, which has an item from self as the parameter and should return a Map.Entry, a Map or a two-element list containing the resulting key and value
      Returns:
        the collector with all transformed values added to it
      See Also:
        collectEntries(Iterator, Map, Closure)
      Since:
        1.8.7

    - #### <K, V> public Map<K, V> collectEntries(Map<K, V> collector)

      A variant of collectEntries for Iterables using the identity closure as the transform and a supplied map as the destination of transformed entries.

      Parameters:
        `collector` - the Map into which the transformed entries are put
      Returns:
        the collector with all transformed values added to it
      See Also:
        collectEntries(Iterator, Map)
      Since:
        1.8.7

    - #### <T, E> public List<T> collectMany(Closure<? extends Collection<? extends T>> projection)

      Projects each item from a source Iterable to a collection and concatenates (flattens) the resulting collections into a single list.

           def nums = 1..10
           def squaresAndCubesOfEvens = nums.collectMany{ it % 2 ? [] : [it**2, it**3] }
           assert squaresAndCubesOfEvens == [4, 8, 16, 64, 36, 216, 64, 512, 100, 1000]

           def animals = ['CAT', 'DOG', 'ELEPHANT'] as Set
           def smallAnimals = animals.collectMany{ it.size() > 3 ? [] : [it.toLowerCase()] }
           assert smallAnimals == ['cat', 'dog']

           def orig = nums as Set
           def origPlusIncrements = orig.collectMany{ [it, it+1] }
           assert origPlusIncrements.size() == orig.size() * 2
           assert origPlusIncrements.unique().size() == orig.size() + 1

      Parameters:
        `projection` - a projecting Closure returning a collection of items
      Returns:
        a list created from the projected collections concatenated (flattened) together
      See Also:
        sum(java.lang.Iterable, groovy.lang.Closure)
      Since:
        2.2.0

    - #### <T, E> public List<T> collectMany(Function<? super E, ? extends Collection<? extends T>> projection)

      Projects each item from a source Iterable to a collection and concatenates (flattens) the resulting collections into a single list. A "fat-free" variant of Iterable.collectMany accepting a Function.

           def nums = 1..10
           def squaresAndCubesOfEvens = nums.collectMany(n -> n % 2 ? [] : [n**2, n**3])
           assert squaresAndCubesOfEvens == [4, 8, 16, 64, 36, 216, 64, 512, 100, 1000]

      Parameters:
        `projection` - a projecting function returning a collection of items
      Returns:
        a list created from the projected collections concatenated (flattened) together
      Since:
        6.0.0

    - #### <T, E> public List<T> collectMany()

      Flattens an iterable of collections into a list.

      Returns:
        the flattened list of elements
      Since:
        5.0.0

    - #### <T, E, C extends java.util.Collection<T>> public C collectMany(C collector, Closure<? extends Collection<? extends T>> projection)

      Projects each item from a source collection to a result collection and concatenates (flattens) the resulting collections adding them into the `collector`.

           def animals = ['CAT', 'DOG', 'ELEPHANT']
           def smallAnimals = animals.collectMany(['ant', 'bee']){ it.size() > 3 ? [] : [it.toLowerCase()] }
           assert smallAnimals == ['ant', 'bee', 'cat', 'dog']

           def nums = 1..5
           def origPlusIncrements = nums.collectMany([] as Set){ [it, it+1] }
           assert origPlusIncrements.size() == nums.size() + 1

           @groovy.transform.TypeChecked void test() {
             LinkedHashSet<String> lhs = ['abc','def'].collectMany(new LinkedHashSet<>()){ it.iterator().toList() }
             assert lhs == ['a','b','c','d','e','f'] as Set<String>
           }
           test()

      Parameters:
        `collector` - an initial collection to add the projected items to
        `projection` - a projecting Closure returning a collection of items
      Returns:
        the collector with the projected collections concatenated (flattened) into it
      Since:
        2.2.0

    - #### <T, E, C extends java.util.Collection<T>> public C collectMany(C collector, Function<? super E, ? extends Collection<? extends T>> projection)

      Projects each item from a source collection to a result collection and concatenates (flattens) the resulting collections adding them into the `collector`. A "fat-free" variant of Iterable.collectMany accepting a Function.

           def animals = ['CAT', 'DOG', 'ELEPHANT']
           def smallAnimals = animals.collectMany(['ant', 'bee'], a -> a.size() > 3 ? [] : [a.toLowerCase()])
           assert smallAnimals == ['ant', 'bee', 'cat', 'dog']

      Parameters:
        `collector` - an initial collection to add the projected items to
        `projection` - a projecting function returning a collection of items
      Returns:
        the collector with the projected collections concatenated (flattened) into it
      Since:
        6.0.0

    - #### public List collectNested(Closure transform)

      Recursively iterates through this Iterable transforming each non-Collection value into a new value using the closure as a transformer. Returns a potentially nested list of transformed values.

           assert [2,[4,6],[8],[]] == [1,[2,3],[4],[]].collectNested { it * 2 }

      Parameters:
        `transform` - the closure used to transform each item of the Iterable
      Returns:
        the resultant list
      Since:
        2.2.0

    - #### <C extends java.util.Collection> public C collectNested(C collector, Closure transform)

      Recursively iterates through this Iterable transforming each non-Collection value into a new value using the `transform` closure. Returns a potentially nested collection of transformed values.

           def x = [1,[2,3],[4],[]].collectNested(new Vector()) { it * 2 }
           assert x == [2,[4,6],[8],[]]
           assert x instanceof Vector

      Parameters:
        `collector` - an initial Collection to which the transformed values are added
        `transform` - the closure used to transform each element of the Iterable
      Returns:
        the collector with all transformed values added to it
      Since:
        2.2.0

    - #### public List<List> combinations()

      Finds all combinations of items from the given aggregate of collections.

      Example usage:

           result = [['a', 'b'], [1, 2, 3]].combinations()
           assert result == [['a', 1], ['b', 1], ['a', 2], ['b', 2], ['a', 3], ['b', 3]]

      Returns:
        A list of the combinations (lists).
      See Also:
        GroovyCollections.combinations
      Since:
        2.2.0

    - #### <T> public List<T> combinations(Closure<T> function)

      Finds all combinations of items from the given aggregate of collections, then returns the results of the supplied transform.

      Example usage:

           result = [[2, 3], [4, 5, 6]].combinations { x,y -> x*y }
           assert result == [8, 12, 10, 15, 12, 18]

      Parameters:
        `function` - a closure to be called on each combination (list)
      Returns:
        A list of the results of applying the closure to each combination.
      See Also:
        GroovyCollections.combinations
        collect(Iterable,Closure)
      Since:
        2.2.0

    - #### public boolean contains(Object item)

      Returns `true` if this iterable contains the item.

      Parameters:
        `item` - an Object to be checked for containment in this iterable
      Returns:
        `true` if this iterable contains the item
      See Also:
        Collection.contains
      Since:
        2.4.0

    - #### public boolean containsAll(Object[] items)

      Returns `true` if this iterable contains all the elements in the specified array.

      Parameters:
        `items` - array to be checked for containment in this iterable
      Returns:
        `true` if this collection contains all the elements in the specified array
      See Also:
        Collection.containsAll
      Since:
        2.4.0

    - #### public Number count(Object value)

      Counts the number of occurrences of the given value inside this Iterable. Comparison is done using Groovy's == operator (using `compareTo(value) == 0` or `equals(value)` ).

      Example usage:

           assert [2,4,2,1,3,5,2,4,3].count(4) == 2

      Parameters:
        `value` - the value being searched for
      Returns:
        the number of occurrences
      Since:
        2.2.0

    - #### <T> public Number count(Closure closure)

      Counts the number of occurrences which satisfy the given closure from inside this Iterable.

      Example usage:

           assert [2,4,2,1,3,5,2,4,3].count{ it % 2 == 0 } == 5

      Parameters:
        `closure` - a closure condition
      Returns:
        the number of occurrences
      Since:
        2.2.0

    - #### <T> public Number count(Predicate<? super T> predicate)

      Counts the number of occurrences which satisfy the given predicate from inside this Iterable. A "fat-free" variant of Iterable.count accepting a Predicate.

      Example usage:

           import java.util.function.Predicate
           Predicate<Integer> isEven = n -> n % 2 == 0
           assert [2, 4, 2, 1, 3, 5, 2, 4, 3].count(isEven) == 5

      Parameters:
        `predicate` - a predicate condition
      Returns:
        the number of occurrences
      Since:
        6.0.0

    - #### <T, P> public Number count(BiPredicate<? super T, ? super P> predicate, P param)

      Counts the number of occurrences which satisfy the given two-argument condition, with the supplied `param` fixed as the second argument. Combines Iterable.count with the right-currying performed by Lambdas.curryWith, so that `list.count(condition, param)` is equivalent to `list.count(curryWith(condition, param))`.

      Example usage:

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert [2, 4, 2, 1, 3, 5, 2, 4, 3].count(divisibleBy, 2) == 5

      Parameters:
        `predicate` - a two-argument predicate condition
        `param` - the value to fix as the predicate's second argument
      Returns:
        the number of occurrences
      Since:
        6.0.0

    - #### <T, E extends java.lang.Number> public E count(E initialCount, Closure closure)

      Counts the number of occurrences which satisfy the given closure from inside this Iterable.

      Example usage:

           assert [2,4,2,1,3,5,2,4,3].count(100L){ it % 2 == 0 } == 105L

      Parameters:
        `initialCount` - start counting from this value
        `closure` - a closure condition
      Returns:
        the number of occurrences
      Since:
        4.0.14

    - #### <K, E> public Map<K, Integer> countBy(Closure<K> closure)

      Sorts all collection members into groups determined by the supplied mapping closure and counts the group size. The closure should return the key that each item should be grouped by. The returned Map will have an entry for each distinct key returned from the closure, with each value being the frequency of items occurring for that group.

      Example usage:

          assert [0:2, 1:3] == [1,2,3,4,5].countBy { it % 2 }

      Parameters:
        `closure` - a closure mapping items to the frequency keys
      Returns:
        a new Map grouped by keys with frequency counts
      Since:
        2.2.0

    - #### <K, E> public Map<K, Integer> countBy(Function<? super E, ? extends K> function)

      Sorts all collection members into groups determined by the supplied mapping function and counts the group size. A "fat-free" variant of Iterable.countBy accepting a Function.

           assert [0: 2, 1: 3] == [1, 2, 3, 4, 5].countBy(n -> n % 2)

      Parameters:
        `function` - a function mapping items to the frequency keys
      Returns:
        a new Map grouped by keys with frequency counts
      Since:
        6.0.0

    - #### <E> public Map<E, Integer> countBy()

      Creates a multiset-like map of the collection members.

      Example usage:

          assert [1:2, 2:2, 3:1] == [1,2,1,2,3].countBy()

      Returns:
        a new Map where the keys are the set of values in the collection and the values are the frequency counts
      Since:
        5.0.0

    - #### public boolean disjoint(Iterable right)

      Returns `true` if the intersection of two iterables is empty.

          assert [1,2,3].disjoint([3,4,5]) == false

          assert [1,2].disjoint([3,4]) == true

      Parameters:
        `right` - an Iterable
      Returns:
        boolean `true` if the intersection of two iterables is empty, `false` otherwise.
      Since:
        2.4.0

    - #### <T> public Collection<T> drop(int num)

      Drops the given number of elements from the head of this Iterable.

           def strings = [ 'a', 'b', 'c' ]
           assert strings.drop( 0 ) == [ 'a', 'b', 'c' ]
           assert strings.drop( 2 ) == [ 'c' ]
           assert strings.drop( 5 ) == []

           class AbcIterable implements Iterable {
               Iterator iterator() { "abc".iterator() }
           }
           def abc = new AbcIterable()
           assert abc.drop(0) == ['a', 'b', 'c']
           assert abc.drop(1) == ['b', 'c']
           assert abc.drop(3) == []
           assert abc.drop(5) == []

      Parameters:
        `num` - the number of elements to drop from this Iterable
      Returns:
        a Collection consisting of all the elements of this Iterable minus the first `num` elements, or an empty list if it has less than `num` elements.
      Since:
        1.8.7

    - #### <T> public Collection<T> dropRight(int num)

      Drops the given number of elements from the tail of this Iterable.

           def strings = [ 'a', 'b', 'c' ]
           assert strings.dropRight( 0 ) == [ 'a', 'b', 'c' ]
           assert strings.dropRight( 2 ) == [ 'a' ]
           assert strings.dropRight( 5 ) == []

           class AbcIterable implements Iterable {
               Iterator iterator() { "abc".iterator() }
           }
           def abc = new AbcIterable()
           assert abc.dropRight(0) == ['a', 'b', 'c']
           assert abc.dropRight(1) == ['a', 'b']
           assert abc.dropRight(3) == []
           assert abc.dropRight(5) == []

      Parameters:
        `num` - the number of elements to drop from this Iterable
      Returns:
        a Collection consisting of all the elements of this Iterable minus the last `num` elements, or an empty list if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public Collection<T> dropWhile(Closure condition)

      Returns a suffix of this Iterable where elements are dropped from the front while the given closure evaluates to true.

           class HorseIterable implements Iterable {
               Iterator iterator() { "horse".iterator() }
           }
           def horse = new HorseIterable()
           assert horse.dropWhile{ it < 'r' } == ['r', 's', 'e']
           assert horse.dropWhile{ it <= 'r' } == ['s', 'e']

      Parameters:
        `condition` - the closure that must evaluate to true to continue dropping elements
      Returns:
        a Collection containing the shortest suffix of the given Iterable such that the given closure condition evaluates to true for each element dropped from the front of the Iterable
      Since:
        1.8.7

    - #### <T> public Collection<T> dropWhile(Predicate<? super T> condition)

      Returns a suffix of an Iterable where elements are dropped from the front while the predicate is satisfied. A "fat-free" variant of Iterable.dropWhile accepting a Predicate.

           assert (1..5).dropWhile(n -> n < 3) == [3, 4, 5]

      Parameters:
        `condition` - the predicate that must evaluate to true to continue dropping elements
      Returns:
        the shortest suffix of the given Iterable such that its first element does not pass the given predicate
      Since:
        6.0.0

    - #### <T> public Iterable<T> each(Closure closure)

      Iterates through an Iterable, passing each item to the given closure.

      Parameters:
        `closure` - the closure applied on each element found
      Returns:
        the self Iterable

    - #### <T> public Iterable<T> each(Consumer<? super T> consumer)

      Iterates through an Iterable, passing each item to the given consumer. A "fat-free" variant of Iterable.each accepting a Consumer.

           def result = []
           assert [1, 2, 3].each(result::add) == [1, 2, 3]
           assert result == [1, 2, 3]

      Parameters:
        `consumer` - the consumer applied on each element found
      Returns:
        the self Iterable
      Since:
        6.0.0

    - #### public void eachCombination(Closure<?> function)

      Applies a function on each combination of the input lists.

      Example usage:

          [[2, 3],[4, 5, 6]].eachCombination { println "Found $it" }

      Parameters:
        `function` - a closure to be called on each combination
      See Also:
        GroovyCollections.combinations
      Since:
        2.2.0

    - #### <T> public Iterator<List<T>> eachPermutation(Closure closure)

      Iterates over all permutations of a collection, running a closure for each iteration.

      Example usage:

          def permutations = []
           [1, 2, 3].eachPermutation{ permutations << it }
           assert permutations == [[1, 2, 3], [1, 3, 2], [2, 1, 3], [2, 3, 1], [3, 1, 2], [3, 2, 1]]

      Parameters:
        `closure` - the closure to call for each permutation
      Returns:
        the permutations from the list
      Since:
        1.7.0

    - #### <T> public Iterable<T> eachWithIndex(Closure closure)

      Iterates through an iterable type, passing each item and the item's index (a counter starting at zero) to the given closure.

      Parameters:
        `closure` - a Closure to operate on each item
      Returns:
        the self Iterable
      Since:
        2.3.0

    - #### <T> public Iterable<T> eachWithIndex(ObjIntConsumer<? super T> consumer)

      Iterates through an Iterable, passing each item and the item's index (a counter starting at zero) to the given consumer. A "fat-free" variant of Iterable.eachWithIndex accepting an ObjIntConsumer.

           def result = [:]
           ['a', 'b', 'c'].eachWithIndex((item, index) -> result[item] = index)
           assert result == [a: 0, b: 1, c: 2]

      Parameters:
        `consumer` - a consumer which accepts each item and its index
      Returns:
        the self Iterable
      Since:
        6.0.0

    - #### <T> public boolean every(Closure predicate)

      Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this iterable). A simple example for a list:

          def list = [3,4,5]
           def greaterThanTwo = list.every { it > 2 }

      Parameters:
        `predicate` - the closure predicate used for matching
      Returns:
        true if every iteration of the object matches the closure predicate
      Since:
        2.3.0

    - #### <T> public boolean every(Predicate<? super T> predicate)

      Used to determine if the given predicate is valid (i.e. returns `true` for all items in this iterable). A "fat-free" variant of Iterable.every accepting a Predicate.

           import java.util.function.Predicate
           Predicate<Integer> greaterThanTwo = n -> n > 2
           assert [3, 4, 5].every(greaterThanTwo)
           assert ![1, 4, 5].every(greaterThanTwo)

      Parameters:
        `predicate` - the predicate used for matching
      Returns:
        true if every element of the iterable matches the predicate
      Since:
        6.0.0

    - #### <T, P> public boolean every(BiPredicate<? super T, ? super P> predicate, P param)

      Used to determine if the given predicate is valid (i.e. returns `true` for all items in this iterable) when called with each element and the supplied `param`. A "fat-free" variant of Iterable.every accepting a BiPredicate together with an additional argument, mirroring Iterable.findAll.

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert [2, 4, 6].every(divisibleBy, 2)
           assert ![2, 3, 4].every(divisibleBy, 2)

      Parameters:
        `predicate` - the predicate used for matching
        `param` - the additional argument passed to the predicate
      Returns:
        true if every element of the iterable matches the predicate
      Since:
        6.0.0

    - #### <T> public T find(Predicate<? super T> condition)

      Finds the first value matching the given predicate. A "fat-free" variant of Collection.find accepting a Predicate.

           import java.util.function.Predicate
           Predicate<Integer> greaterThanOne = n -> n > 1
           assert [1, 2, 3].find(greaterThanOne) == 2
           assert [1, 2, 3].find(n -> n > 3) == null

      Parameters:
        `condition` - the predicate condition
      Returns:
        the first element matching the condition, in iteration order, or null if none matches
      Since:
        6.0.0

    - #### <T, P> public T find(BiPredicate<? super T, ? super P> condition, P param)

      Finds the first value matching the given two-argument condition, with the supplied `param` fixed as the second argument. This is the single-result counterpart of Iterable.findAll, combining Iterable.find with the right-currying performed by Lambdas.curryWith, so that `list.find(condition, param)` is equivalent to `list.find(curryWith(condition, param))`.

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert [1, 2, 3, 4, 5, 6].find(divisibleBy, 3) == 3
           assert [1, 2, 3, 4, 5, 6].find(divisibleBy, 7) == null

      Parameters:
        `condition` - a two-argument predicate condition
        `param` - the value to fix as the predicate's second argument
      Returns:
        the first element matching the condition, in iteration order, or null if none matches
      Since:
        6.0.0

    - #### <T> public List<T> findAll(Predicate<? super T> condition)

      Finds all values matching the given predicate. A "fat-free" variant of Collection.findAll accepting a Predicate.

          assert [2, 4] == [1, 2, 3, 4].findAll(n -> n % 2 == 0)

      Parameters:
        `condition` - the predicate condition
      Returns:
        a List of matching values
      Since:
        6.0.0

    - #### <T, P> public List<T> findAll(BiPredicate<? super T, ? super P> condition, P param)

      Finds all values matching the given two-argument condition, with the supplied `param` fixed as the second argument. This is a "fat-free" variant combining Iterable.findAll with the right-currying performed by Lambdas.curryWith, so that `list.findAll(condition, param)` is equivalent to `list.findAll(curryWith(condition, param))`.

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert [1, 2, 3, 4, 5, 6].findAll(divisibleBy, 2) == [2, 4, 6]
           assert [1, 2, 3, 4, 5, 6].findAll(divisibleBy, 3) == [3, 6]

      Parameters:
        `condition` - a two-argument predicate condition
        `param` - the value to fix as the predicate's second argument
      Returns:
        a List of matching values
      Since:
        6.0.0

    - #### <T> public int findIndexOf(Closure condition)

      Iterates over the elements of an Iterable and returns the index of the first item that satisfies the condition specified by the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public int findIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index of the first item that satisfies the condition specified by the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the first matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public List<Number> findIndexValues(Closure condition)

      Iterates over the elements of an Iterable and returns the index values of the items that match the condition specified in the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        a list of numbers corresponding to the index values of all matched objects
      Since:
        2.5.0

    - #### <T> public List<Number> findIndexValues(Number startIndex, Closure condition)

      Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index values of the items that match the condition specified in the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        a list of numbers corresponding to the index values of all matched objects
      Since:
        2.5.0

    - #### <T> public int findLastIndexOf(Closure condition)

      Iterates over the elements of an Iterable and returns the index of the last item that matches the condition specified in the closure.

      Parameters:
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <T> public int findLastIndexOf(int startIndex, Closure condition)

      Iterates over the elements of an Iterable, starting from a specified startIndex, and returns the index of the last item that matches the condition specified in the closure.

      Parameters:
        `startIndex` - start matching from this index
        `condition` - the matching condition
      Returns:
        an integer that is the index of the last matched object or -1 if no match was found
      Since:
        2.5.0

    - #### <S, T, U extends T, V extends T> public T findResult(U defaultResult, Closure<V> condition)

      Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result. If all are null, the defaultResult is returned.

      Examples:

           def list = [1,2,3]
           assert "Found 2" == list.findResult("default") { it > 1 ? "Found $it" : null }
           assert "default" == list.findResult("default") { it > 3 ? "Found $it" : null }

      Parameters:
        `defaultResult` - an Object that should be returned if all closure results are null
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result from calling the closure, or the defaultValue
      Since:
        2.5.0

    - #### <T, U extends T, V extends T> public T findResult(V defaultResult)

      Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result. If all are null, the defaultResult is returned.

      Examples:

           assert [null, 1, 2].findResult('default') == 1
           assert [null, null].findResult('default') == 'default'

      Parameters:
        `defaultResult` - an Object that should be returned if all elements in the iterable are null
      Returns:
        the first non-null element from the iterable, or the defaultValue
      Since:
        4.0.9

    - #### <T, U> public T findResult(Closure<T> condition)

      Iterates through the Iterable calling the given closure condition for each item but stopping once the first non-null result is found and returning that result. If all results are null, null is returned.

      Parameters:
        `condition` - a closure that returns a non-null value to indicate that processing should stop and the value should be returned
      Returns:
        the first non-null result from calling the closure, or null
      Since:
        2.5.0

    - #### <T> public T findResult()

      Iterates through the Iterable stopping once the first non-null result is found and returning that result. If all results are null, null is returned.

      Returns:
        the first non-null element from the iterable, or null
      Since:
        4.0.9

    - #### <T, U> public Collection<T> findResults(Closure<T> filteringTransform)

      Iterates through the Iterable transforming items using the supplied closure and collecting any non-null results.

      Example:

           def list = [1,2,3]
           def result = list.findResults { it > 1 ? "Found $it" : null }
           assert result == ["Found 2", "Found 3"]

      Parameters:
        `filteringTransform` - a Closure that should return either a non-null transformed value or null for items which should be discarded
      Returns:
        the list of non-null transformed values
      Since:
        2.2.0

    - #### <T> public Collection<T> findResults()

      Iterates through the Iterable collecting any non-null results.

      Example:

           assert [1, null, 2, null, 3].findResults() == [1, 2, 3]

      Returns:
        the list of non-null values
      Since:
        4.0.9

    - #### <T> public T first()

      Returns the first item from the Iterable.

           def set = [3, 4, 2] as LinkedHashSet
           assert set.first() == 3
           // check original is unaltered
           assert set == [3, 4, 2] as Set

      The first element returned by the Iterable's iterator is returned. If the Iterable doesn't guarantee a defined order it may appear like a random element is returned.
      throws:
        NoSuchElementException if you try to access first() for an empty Iterable
      Returns:
        the first item from the Iterable
      Since:
        1.8.7

    - #### <T, E> public Collection<T> flatten()

      Flatten an Iterable. This Iterable and any nested arrays or collections have their contents (recursively) added to the new collection.

          assert [1,2,3,4,5] == [1,[2,3],[[4]],[],5].flatten()

      Returns:
        a flattened Collection
      Since:
        1.6.0

    - #### <T, E> public Collection<T> flatten(boolean flattenOptionals)

      Flatten an Iterable. This Iterable and any nested arrays or collections have their contents (recursively) added to the new collection. If flattenOptionals is true, the non-empty optionals are also flattened.

      Example:

           var items = [1..2, [3, [4]], Optional.of(5), Optional.empty()]
           assert items.flatten() == [1, 2, 3, 4, 5]
           // boolean param determines whether to flatten optionals (false for legacy behavior)
           assert items.flatten(true) == [1, 2, 3, 4, 5]
           assert items.flatten(false) == [1, 2, 3, 4, Optional.of(5), Optional.empty()]

      Parameters:
        `flattenOptionals` - whether to treat an Optional as a container to flatten
      Returns:
        a flattened Collection
      Since:
        5.0.0

    - #### <T, E> public Collection<T> flatten(Closure<?> flattenUsing)

      Flatten an Iterable. This Iterable and any nested arrays, collections, or optionals have their contents (recursively) added to a new collection. Non-Array, non-Collection, non-Optional objects are leaf nodes. The flattenUsing transform can be used to modify leaf nodes. If a leaf node represents some other kind of collective type, the supplied closure should yield the contained items; otherwise, the closure should just return the (optionally modified) leaf.

      Example:

           // some examples just transforming the leaf
           var items = [1..2, [3, [4]]]
           assert items.flatten(n -> n + 5) == 6..9
           assert items.flatten{ 'x' * it } == ['x', 'xx', 'xxx', 'xxxx']

           // Here our String is a "container" of day, month, year parts
           var dates = ['01/02/99', '12/12/23']
           assert dates.flatten{ it.split('/') } == [['01', '02', '99'], ['12', '12', '23']]
           assert dates.flatten{ it.split('/').toList() } == ['01', '02', '99', '12', '12', '23']

           // some examples with Maps
           assert [a:1, b:2].entrySet().flatten{ "$it.key$it.value" } == ['a1', 'b2'] as Set
           assert [[a:1], [b:2]].flatten{ it.keySet() + it.values() } == ['a', 1, 'b', 2]

      Parameters:
        `flattenUsing` - a closure to determine how to flatten non-Array, non-Collection elements
      Returns:
        a flattened Collection
      See Also:
        flattenMany(Iterable, Closure)
        collectNested(Iterable, Closure)
      Since:
        1.6.0

    - #### <T, E> public Collection<T> flatten(boolean flattenOptionals, Closure<?> flattenUsing)

      Flatten an Iterable. This Iterable and any nested arrays, collections, and potentially Optional elements have their contents (recursively) added to a new collection. Non-container elements are leaf elements. If flattenOptionals is false, Optionals are treated as leaf elements, otherwise they are considered as containers to flatten. The flattenUsing transform can be used to modify leaf nodes. If a leaf node represents some other kind of collective type, the supplied closure should yield the contained item or items; otherwise, the closure should just return the (optionally modified) leaf.

           var items = ['a'..'b', ['c'], Optional.of('d'), Optional.empty()]
           var unknown = { it instanceof Optional ? it.orElse('Unknown') : it.toUpperCase() }

           // by default Optionals are flattened so the ternary in the
           // 'unknown' closure will never see the optional
           assert items.flatten(unknown) == ['A', 'B', 'C', 'D']
           assert items.flatten(true, unknown) == ['A', 'B', 'C', 'D']

           // disable optional flattening and you can provide custom flattening
           assert items.flatten(false, unknown) == ['A', 'B', 'C', 'd', 'Unknown']

      Parameters:
        `flattenOptionals` - whether to treat an Optional as a container to flatten or a leaf
        `flattenUsing` - a closure to determine how to flatten leaf elements
      Returns:
        a flattened Collection
      Since:
        5.0.0

    - #### <T> public Collection<T> flattenMany(Closure<?> transform)

      Flatten an Iterable. This Iterable and any nested arrays, collections or optionals have their contents (recursively) added to a new collection. A transform is applied to any leaf nodes before further flattening.

           var items = ['1', '2', 'foo', '3', 'bar']
           var toInt = s -> s.number ? Optional.of(s.toInteger()) : Optional.empty()
           assert items.flattenMany(toInt) == [1, 2, 3]
           assert items.flattenMany(String::toList) == ['1', '2', 'f', 'o', 'o', '3', 'b', 'a', 'r']
           assert items.flattenMany{ it.split(/[aeiou]/) } == ['1', '2', 'f', '3', 'b', 'r']

           assert ['01/02/99', '12/12/23'].flattenMany{ it.split('/') } == ['01', '02', '99', '12', '12', '23']

      The `flattenMany` method is somewhat similar to the `collectMany` method. While `collectMany` works on the basis that the transform closure returns a collection, `flattenMany` can return a collection, array, optional or modified element. You should use `flattenMany` if you need the extra functionality it offers. Consider using `collectMany` if you return only collections in the transform, since you will have better type inference in static typing scenarios.
      Parameters:
        `transform` - a transform applied to any leaf elements
      Returns:
        a flattened Collection
      See Also:
        collectMany(Iterable, Closure)
      Since:
        5.0.0

    - #### <T> public T getAt(int idx)

      Support the subscript operator for an Iterable. Typical usage:

           // custom Iterable example:
           class MyIterable implements Iterable {
             Iterator iterator() { [1, 2, 3].iterator() }
           }
           def myIterable = new MyIterable()
           assert myIterable[1] == 2

           // Set example:
           def set = [1,2,3] as LinkedHashSet
           assert set[1] == 2

      Parameters:
        `idx` - an index value (-self.size() <= idx < self.size()) but using -ve index values will be inefficient
      Returns:
        the value at the given index (after normalisation) or null if no corresponding value was found
      Since:
        2.1.0

    - #### <K, T> public Map<K, List<T>> groupBy(Closure<K> closure)

      Sorts all Iterable members into groups determined by the supplied mapping closure. The closure should return the key that this item should be grouped by. The returned LinkedHashMap will have an entry for each distinct key returned from the closure, with each value being a list of items for that group.

      Example usage:

           assert [0:[2,4,6], 1:[1,3,5]] == [1,2,3,4,5,6].groupBy { it % 2 }

      Parameters:
        `closure` - a closure mapping entries on keys
      Returns:
        a new Map grouped by keys
      Since:
        2.2.0

    - #### <K, T> public Map<K, List<T>> groupBy(Function<? super T, ? extends K> function)

      Sorts all Iterable members into groups determined by the supplied mapping function. A "fat-free" variant of Iterable.groupBy accepting a Function.

           assert [0: [2, 4, 6], 1: [1, 3, 5]] == [1, 2, 3, 4, 5, 6].groupBy(n -> n % 2)

      Parameters:
        `function` - a function mapping entries on keys
      Returns:
        a new Map grouped by keys
      Since:
        6.0.0

    - #### public Map groupBy(Object closures)

      Sorts all Iterable members into (sub)groups determined by the supplied mapping closures. Each closure should return the key that this item should be grouped by. The returned LinkedHashMap will have an entry for each distinct 'key path' returned from the closures, with each value being a list of items for that 'group path'. Example usage:

          def result = [1,2,3,4,5,6].groupBy({ it % 2 }, { it < 4 })
           assert result == [1:[(true):[1, 3], (false):[5]], 0:[(true):[2], (false):[4, 6]]]

      Another example:

          def sql = groovy.sql.Sql.newInstance(/* ... */)
           def data = sql.rows("SELECT * FROM a_table").groupBy({ it.column1 }, { it.column2 }, { it.column3 })
           if (data.val1.val2.val3) {
               // there exists a record where:
               //   a_table.column1 == val1
               //   a_table.column2 == val2, and
               //   a_table.column3 == val3
           } else {
               // there is no such record
           }

      If an empty array of closures is supplied the IDENTITY Closure will be used.
      Parameters:
        `closures` - an array of closures, each mapping entries on keys
      Returns:
        a new Map grouped by keys on each criterion
      Since:
        2.2.0
      See Also:
        Closure.IDENTITY

    - #### public Map groupBy(List<Closure> closures)

      Sorts all Iterable members into (sub)groups determined by the supplied mapping closures. Each closure should return the key that this item should be grouped by. The returned LinkedHashMap will have an entry for each distinct 'key path' returned from the closures, with each value being a list of items for that 'group path'. Example usage:

           def result = [1,2,3,4,5,6].groupBy([{ it % 2 }, { it < 4 }])
           assert result == [1:[(true):[1, 3], (false):[5]], 0:[(true):[2], (false):[4, 6]]]

      Another example:

           def sql = groovy.sql.Sql.newInstance(/* ... */)
           def data = sql.rows("SELECT * FROM a_table").groupBy([{ it.column1 }, { it.column2 }, { it.column3 }])
           if (data.val1.val2.val3) {
               // there exists a record where:
               //   a_table.column1 == val1
               //   a_table.column2 == val2, and
               //   a_table.column3 == val3
           } else {
               // there is no such record
           }

      If an empty list of closures is supplied the IDENTITY Closure will be used.
      Parameters:
        `closures` - a list of closures, each mapping entries on keys
      Returns:
        a new Map grouped by keys on each criterion
      Since:
        2.2.0
      See Also:
        Closure.IDENTITY

    - #### <T, K> public Map<K, List<T>> groupByMany(Function<? super T, ? extends Iterable<? extends K>> keyFn)

      Groups all items from the iterable into (sub)groups determined by the supplied key mapping closure. The closure should return a list of keys applicable to an item. The item will be grouped under each key from the list. Example usage:

           def people = [
               [name: 'Alice', cities: ['NY', 'LA']],
               [name: 'Bob',   cities: ['NY']],
               [name: 'Cara',  cities: ['LA', 'CHI']]
           ]

           def grouped = people*.name.groupByMany { people.find{ p -> it == p.name }.cities }

           assert grouped == [
               NY  : ['Alice', 'Bob'],
               LA  : ['Alice', 'Cara'],
               CHI : ['Cara']
           ]

      Parameters:
        `keyFn` - a closure returning an Iterable of keys for each element
      Returns:
        a new Map from keys to lists of elements
      Since:
        6.0.0

    - #### <T, U, K> public Map<K, List<U>> groupByMany(Function<? super T, ? extends U> valueFn, Function<? super T, ? extends Iterable<? extends K>> keyFn)

      Groups all elements from the iterable into (sub)groups determined by the supplied key mapping closure. The key mapping closure should return a list of keys applicable to an element. The value returned by mapping the element with the value mapping closure will be grouped under each key from the list. Example usage:

           record Person(String name, List<String> cities) { }

           def people = [
               new Person('Alice', ['NY', 'LA']),
               new Person('Bob', ['NY']),
               new Person('Cara', ['LA', 'CHI'])
           ]

           def grouped = people.groupByMany(Person::name, Person::cities)

           assert grouped == [
               NY  : ['Alice', 'Bob'],
               LA  : ['Alice', 'Cara'],
               CHI : ['Cara']
           ]

      Parameters:
        `valueFn` - a closure which can transform each element before collecting
        `keyFn` - a closure returning an Iterable of keys for each element
      Returns:
        a new Map from keys to lists of elements
      Since:
        6.0.0

    - #### <T> public List<List<T>> groupConsecutive()

      Splits this Iterable into a list of sublists, each a maximal run of adjacent elements considered equal. Element order is preserved and the same value may appear in more than one run (unlike Iterable.groupBy, which builds a map). Equality uses Groovy's number-aware coercion, consistent with Collection.unique.

      Example:

           assert [1, 1, 2, 2, 2, 3, 1, 1].groupConsecutive() == [[1, 1], [2, 2, 2], [3], [1, 1]]
           assert [1, 1L, 1.0, 2, 2].groupConsecutive() == [[1, 1L, 1.0], [2, 2]]
           assert [].groupConsecutive() == []
           assert [7].groupConsecutive() == [[7]]
           // run-length encoding; "dedupe consecutive" is just the run heads
           assert 'aaabbbcccd'.toList().groupConsecutive().collect{ run -> [run[0], run.size()] } == [['a', 3], ['b', 3], ['c', 3], ['d', 1]]
           assert 'aaabbbcccd'.toList().groupConsecutive()*.first().join() == 'abcd'

      Returns:
        a list of the runs of adjacent equal elements
      Since:
        6.0.0

    - #### <T, K> public List<List<T>> groupConsecutive(Function<? super T, ? extends K> keyFn)

      Splits this Iterable into runs of adjacent elements whose key, as computed by the given function, is equal (number-aware coercion). `keyFn` is evaluated exactly once per element.

      Example:

           assert ['apple', 'avocado', 'banana', 'cherry', 'citrus', 'date'].groupConsecutive{ it[0] } == [['apple', 'avocado'], ['banana'], ['cherry', 'citrus'], ['date']]
           assert [1, 3, 5, 2, 4, 7, 9].groupConsecutive{ it % 2 } == [[1, 3, 5], [2, 4], [7, 9]]

      Parameters:
        `keyFn` - extracts the grouping key for each element
      Returns:
        a list of the runs of adjacent key-equal elements
      Since:
        6.0.0

    - #### <T> public List<List<T>> groupConsecutive(BiPredicate<? super T, ? super T> sameRun)

      Splits this Iterable into runs where the given predicate, applied to the current run's previous element and the next element, holds. Use this to opt out of the default number-aware equality, e.g. `{ a, b -> Objects.equals(a, b) }` for strict equality or `{ a, b -> (a <=> b) == 0 }` for natural-order equivalence.

      Example:

           assert [1, 1L, 1.0, 2, 2].groupConsecutive{ a, b -> a.equals(b) } == [[1], [1L], [1.0], [2, 2]]
           assert [1.0G, 1.00G, 2.0G].groupConsecutive{ a, b -> (a <=> b) == 0 } == [[1.0, 1.00], [2.0]]

      Parameters:
        `sameRun` - tests whether the next element continues the current run
      Returns:
        a list of the runs
      Since:
        6.0.0

    - #### <T> public T head()

      Returns the first item from the Iterable.

           def set = [3, 4, 2] as LinkedHashSet
           assert set.head() == 3
           // check original is unaltered
           assert set == [3, 4, 2] as Set

      The first element returned by the Iterable's iterator is returned. If the Iterable doesn't guarantee a defined order it may appear like a random element is returned.
      throws:
        NoSuchElementException if you try to access head() for an empty iterable
      Returns:
        the first item from the Iterable
      Since:
        2.4.0

    - #### <E> public Map<Integer, E> indexed()

      Zips an Iterable with indices in (index, value) order.

      Example usage:

           assert [0: "a", 1: "b"] == ["a", "b"].indexed()
           assert ["0: a", "1: b"] == ["a", "b"].indexed().collect { idx, str -> "$idx: $str" }

      Returns:
        a zipped map with indices
      See Also:
        withIndex(Iterable)
      Since:
        2.4.0

    - #### <E> public Map<Integer, E> indexed(int offset)

      Zips an Iterable with indices in (index, value) order.

      Example usage:

           assert [5: "a", 6: "b"] == ["a", "b"].indexed(5)
           assert ["1: a", "2: b"] == ["a", "b"].indexed(1).collect { idx, str -> "$idx: $str" }

      Parameters:
        `offset` - an index to start from
      Returns:
        a Map (since the keys/indices are unique) containing the elements from the iterable zipped with indices
      See Also:
        withIndex(Iterable, int)
      Since:
        2.4.0

    - #### <T> public Collection<T> init()

      Returns the items from the Iterable excluding the last item. Leaves the original Iterable unchanged.

           def list = [3, 4, 2]
           assert list.init() == [3, 4]
           assert list == [3, 4, 2]

      throws:
        NoSuchElementException if you try to access init() for an empty Iterable
      Returns:
        a Collection without its last element
      Since:
        2.4.0

    - #### <T> public List<List<T>> inits()

      Calculates the init values of this Iterable: the first value will be this list of all items from the iterable and the final one will be an empty list, with the intervening values the results of successive applications of init on the items.

           assert [1, 2, 3, 4].inits() == [[1, 2, 3, 4], [1, 2, 3], [1, 2], [1], []]

      Returns:
        a List of the init values from the given Iterable
      Since:
        2.5.0

    - #### <E extends T, T, V extends T> public T inject(Closure<V> closure)

      Iterates through the given object, passing the first two elements to the closure. The result is passed back (injected) to the closure along with the third element and so on until all elements have been consumed.

           def items = [1, 2, 3, 4]
           def value = items.inject { acc, val -> acc * val }
           assert value == 1 * 2 * 3 * 4

           items = [['a','b'], ['b','c'], ['d','b']]
           value = items.inject { acc, val -> acc.intersect(val) }
           assert value == ['b']

           items = ['j', 'o', 'i', 'n'] as Set
           value = items.inject(String.&plus)
           assert value == 'join'

      throws:
        NoSuchElementException if the iterator is empty
      Parameters:
        `closure` - a closure
      Returns:
        the result of the last closure call
      See Also:
        inject(Iterable, Object, Closure)
      Since:
        5.0.0

    - #### <T> public T inject(BinaryOperator<T> operator)

      Iterates through the given iterable, passing the first two elements to the operator. The result is passed back (injected) to the operator along with the third element and so on until all elements have been consumed. A "fat-free" variant of Iterable.inject accepting a BinaryOperator.

           import java.util.function.BinaryOperator
           BinaryOperator<Integer> mult = (acc, val) -> acc * val
           assert [1, 2, 3, 4].inject(mult) == 1 * 2 * 3 * 4

      throws:
        NoSuchElementException if the iterable is empty
      Parameters:
        `operator` - a binary operator combining the running result with each element
      Returns:
        the result of the last operator call
      Since:
        6.0.0

    - #### <E, T, U extends T, V extends T> public T inject(U initialValue, Closure<V> closure)

      Iterates through the given object, passing in the initial value to the 2-arg closure along with the first item. The result is passed back (injected) into the closure along with the second item. The new result is injected back into the closure along with the third item and so on until further iteration is not possible.

      Also known as `foldLeft` or `reduce` in functional parlance. Examples:

           assert 1*1*2*3*4 == [1,2,3,4].inject(1) { acc, val -> acc * val }

           assert 0+1+2+3+4 == [1,2,3,4].inject(0) { acc, val -> acc + val }

           assert 'The quick brown fox' ==
               ['quick', 'brown', 'fox'].inject('The') { acc, val -> acc + ' ' + val }

           assert 'bat' ==
               ['rat', 'bat', 'cat'].inject('zzz') { min, next -> next < min ? next : min }

           def max = { a, b -> [a, b].max() }
           def animals = ['bat', 'rat', 'cat']
           assert 'rat' == animals.inject('aaa', max)

      Visual representation of the last example above:

              initVal  animals[0]
                 v        v
           max('aaa',   'bat')  =>  'bat'  animals[1]
                                      v       v
                                max('bat',  'rat')  =>  'rat'  animals[2]
                                                          v       v
                                                    max('rat',  'cat')  =>  'rat'

      Parameters:
        `initialValue` - some initial value
        `closure` - a closure
      Returns:
        the result of the last closure call
      Since:
        5.0.0

    - #### <E, U> public U inject(U initialValue, BiFunction<? super U, ? super E, ? extends U> function)

      Iterates through the given iterable, passing in the initial value to the function along with the first item. The result is passed back (injected) into the function along with the second item and so on until all elements have been consumed.

      Also known as `foldLeft` or `reduce` in functional parlance. A "fat-free" variant of Iterable.inject accepting a BiFunction.

           import java.util.function.BiFunction
           BiFunction<Integer, Integer, Integer> add = (acc, val) -> acc + val
           assert [1, 2, 3, 4].inject(0, add) == 0 + 1 + 2 + 3 + 4
           assert ['quick', 'brown', 'fox'].inject('The', (acc, val) -> acc + ' ' + val) == 'The quick brown fox'

      Parameters:
        `initialValue` - some initial value
        `function` - a function combining the running result with each element
      Returns:
        the result of the last function call
      Since:
        6.0.0

    - #### <E, T, U extends T, V extends T> public List<T> injectAll(U initialValue, Closure<V> closure)

      Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.

      Also known as prefix sum or scan in functional parlance. Example:

           assert (1..3).injectAll(''){ carry, next -> carry + next } == ['1', '12', '123']
           var runningAvg = [1.0, 2.0, 3.0].injectAll([0.0, 0, null]){ accum, next ->
               var total = accum[0] + next
               var count = accum[1] + 1
               [total, count, total/count]
           }
           assert runningAvg*.get(2) == [1.0, 1.5, 2.0]

      Parameters:
        `initialValue` - some initial value
        `closure` - a closure
      Returns:
        the list of all calculated values
      Since:
        5.0.0

    - #### <E, U> public List<U> injectAll(U initialValue, BiFunction<? super U, ? super E, ? extends U> function)

      Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result. A "fat-free" variant of Iterable.injectAll accepting a BiFunction.

      Also known as prefix sum or scan in functional parlance.

           import java.util.function.BiFunction
           BiFunction<String, Integer, String> concat = (carry, next) -> carry + next
           assert (1..3).injectAll('', concat) == ['1', '12', '123']

      Parameters:
        `initialValue` - some initial value
        `function` - a function combining the running result with each element
      Returns:
        the list of all calculated values
      Since:
        6.0.0

    - #### <E extends T, T, V extends T> public List<T> injectAll(Closure<V> closure)

      Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result.

      Example:

           assert (1..5).injectAll { carry, next -> carry + next } == [3, 6, 10, 15]
           assert (1..5).injectAll(Integer::plus) == [3, 6, 10, 15]

      See Also:
        injectAll(Iterable, Closure)
      Since:
        5.0.0

    - #### <T> public List<T> injectAll(BinaryOperator<T> operator)

      Iterates through the given iterable, injecting values as per `inject` but returns the list of all calculated values instead of just the final result. A "fat-free" variant of Iterable.injectAll accepting a BinaryOperator.

           import java.util.function.BinaryOperator
           BinaryOperator<Integer> add = (a, b) -> a + b
           assert (1..5).injectAll(add) == [3, 6, 10, 15]

      throws:
        NoSuchElementException if the iterable is empty
      Parameters:
        `operator` - a binary operator combining the running result with each element
      Returns:
        the list of all calculated values
      Since:
        6.0.0

    - #### <T, U extends T, V extends T> public List<T> interleave(Iterable<V> other)

      The elements from two Iterables interleaved. If the iterables are of different sizes, the result will have the same size as the shorter one.

      Example:

           def abc = 'A'..'C'
           def nums = 1..2
           assert ['A', 1, 'B', 2] == abc.interleave(nums)
           assert [1, 'A', 2, 'B'] == nums.interleave(abc)

      Parameters:
        `other` - another Iterable
      Returns:
        a list of all the pairs from self and other interleaved
      Since:
        5.0.0

    - #### <T, U extends T, V extends T> public List<T> interleave(Iterable<V> other, boolean includeRemainder)

      The elements from two Iterables interleaved. If the sources are of different sizes, and `includeRemainder` is true, the extra elements from the longer source will be appended after interleaving.

      Example:

           def items = (1..4)
           def other = [10, 20]
           assert [1, 10, 2, 20, 3, 4] == items.interleave(other, true)

      When `includeRemainder` is false, this is equivalent to `zip` then `collectMany`.

      Parameters:
        `other` - another Iterable
      Returns:
        a list of all the pairs from self and other interleaved
      See Also:
        for zipping more than two lists
      Since:
        5.0.0

    - #### <T> public Collection<T> intersect(Iterable<T> right)

      Create a Collection composed of the intersection of both iterables. Any elements that exist in both iterables are added to the resultant collection. For iterables of custom objects; the objects should implement java.lang.Comparable

           assert [4,5] == [1,2,3,4,5].intersect([4,5,6,7,8])

      By default, Groovy uses a NumberAwareComparator when determining if an element exists in both collections.
      Parameters:
        `right` - an Iterable
      Returns:
        a Collection as an intersection of both iterables
      See Also:
        intersect(Iterable, Iterable, Comparator)
      Since:
        2.4.0

    - #### <T> public Collection<T> intersect(Iterable<T> right, Comparator<? super T> comparator)

      Create a Collection composed of the intersection of both iterables. Any elements that exist in both iterables are added to the resultant collection. For iterables of custom objects; the objects should implement java.lang.Comparable

           assert [3,4] == [1,2,3,4].intersect([3,4,5,6], Comparator.naturalOrder())

      Parameters:
        `right` - an Iterable
        `comparator` - a Comparator
      Returns:
        a Collection as an intersection of both iterables
      Since:
        2.5.0

    - #### <T> public Collection<T> intersect(Iterable<T> right, Closure condition)

      Create a Collection composed of the intersection of both iterables. Elements from teh first iterable which also occur (according to the comparator closure) in the second iterable are added to the result. If the closure takes a single parameter, the argument passed will be each element, and the closure should return a value used for comparison (either using Comparable.compareTo or Object.equals). If the closure takes two parameters, two items from the Iterator will be passed as arguments, and the closure should return an int value (with 0 indicating the items are deemed equal).

           def one = ['a', 'B', 'c', 'd']
           def two = ['b', 'C', 'd', 'e']
           def compareIgnoreCase = { it.toLowerCase() }
           assert one.intersect(two, compareIgnoreCase) == ['B', 'c', 'd']
           assert two.intersect(one, compareIgnoreCase) == ['b', 'C', 'd']

      Parameters:
        `right` - an Iterable
        `condition` - a Closure used to determine unique items
      Returns:
        a Collection as an intersection of both iterables
      Since:
        4.0.0

    - #### public boolean isCase(Object switchValue)

      Special 'case' implementation for iterables which tests if the 'switch' operand is contained in any of the 'case' values. For example:

          Iterable it = {[1,3,5].iterator()}
           switch( 3 ) {
             case it:
               assert true
               break
             default:
               assert false
           }

           // GROOVY-7919
           assert 1 in it
           assert 2 !in it

      Parameters:
        `switchValue` - the switch value
      Returns:
        true if the caseValue is deemed to contain the switchValue
      See Also:
        contains(Iterable,Object)
      Since:
        5.0.0

    - #### public boolean isEmpty()

      Check whether an `Iterable` has elements

           def items = [1]
           def iterable = { [ hasNext:{ !items.isEmpty() }, next:{ items.pop() } ] as Iterator } as Iterable
           assert !iterable.isEmpty()
           iterable.iterator().next()
           assert iterable.isEmpty()

      Returns:
        true if the iterable has no elements, false otherwise
      Since:
        2.5.0

    - #### <T> public boolean isSorted()

      Determines if the Iterable is sorted. Assumes the elements are comparable and uses a NumberAwareComparator to determine the order.

           assert [1, 2, 3].isSorted()
           assert !([3, 1, 2].isSorted())
           assert [].isSorted()

      Returns:
        true if the elements are sorted in non-descending order
      See Also:
        isSorted(Iterable, Comparator)
      Since:
        6.0.0

    - #### <T> public boolean isSorted(Comparator<? super T> comparator)

      Determines if the Iterable is sorted according to the given Comparator. This is efficient — it checks adjacent pairs in a single pass and short-circuits on the first out-of-order pair. `SortedSet` instances always return `true`.

           assert ["hello","Hey","hi"].isSorted(String.CASE_INSENSITIVE_ORDER)
           assert !(["hi","Hey","hello"].isSorted(String.CASE_INSENSITIVE_ORDER))
           assert (new TreeSet(["c","a","b"])).isSorted()

      Parameters:
        `comparator` - a Comparator used for the comparison
      Returns:
        true if the elements are sorted according to the comparator
      Since:
        6.0.0

    - #### <T> public boolean isSorted(Function<? super T, ?> keyExtractor)

      Determines if the Iterable is sorted in non-descending order of the keys returned by the given key extractor. Keys are compared number-aware, consistent with Iterable.isSorted. For a custom ordering use Iterable.isSorted (a two-arg closure coerces to a Comparator).

           assert ["hi","hey","hello"].isSorted { it.length() }
           assert !["hello","hi","hey"].isSorted { it.length() }
           assert ["hi","hey","hello"].isSorted { a, b -> a.length() <=> b.length() } // Comparator overload

      Parameters:
        `keyExtractor` - extracts the sort key from each element
      Returns:
        true if the elements are sorted by key in non-descending order
      See Also:
        isSorted(Iterable, Comparator)
      Since:
        6.0.0

    - #### public String join()

      Concatenates the `toString()` representation of each item from the Iterable.

          assert [1,2,3].join() == "123"

      Returns:
        the joined String
      Since:
        5.0.0

    - #### public String join(String separator)

      Concatenates the `toString()` representation of each item from the Iterable, with the given String as a separator between each item.

          assert [1,2,3].join(", ") == "1, 2, 3"

      Parameters:
        `separator` - a String separator
      Returns:
        the joined String
      Since:
        1.0

    - #### <T> public T last()

      Returns the last item from the Iterable.

           def set = [3, 4, 2] as LinkedHashSet
           assert set.last() == 2
           // check original unaltered
           assert set == [3, 4, 2] as Set

      The last element returned by the Iterable's iterator is returned. If the Iterable doesn't guarantee a defined order it may appear like a random element is returned.
      throws:
        NoSuchElementException if you try to access last() for an empty Iterable
      Returns:
        the last item from the Iterable
      Since:
        1.8.7

    - #### <T> public T max()

      Adds max() method to Iterable objects.

           assert 5 == [2,3,1,5,4].max()

      Returns:
        the maximum value
      See Also:
        max(Iterator)
      Since:
        2.2.0

    - #### <T> public T max(Comparator<? super T> comparator)

      Selects the maximum value found in the Iterable using the given comparator.

           assert "hello" == ["hello","hi","hey"].max( { a, b -> a.length() <=> b.length() } as Comparator )

      Parameters:
        `comparator` - a Comparator
      Returns:
        the maximum value or null for an empty Iterable
      See Also:
        max(Iterator, Comparator)
      Since:
        2.2.0

    - #### <T> public T max(Closure closure)

      Selects the item in the iterable which when passed as a parameter to the supplied closure returns the maximum value. A null return value represents the least possible return value, so any item for which the supplied closure returns null, won't be selected (unless all items return null). If more than one item has the maximum value, an arbitrary choice is made between the items having the maximum value.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

          assert "hello" == ["hello","hi","hey"].max { it.length() }

          assert "hello" == ["hello","hi","hey"].max { a, b -> a.length() <=> b.length() }

           def pets = ['dog', 'elephant', 'anaconda']
           def longestName = pets.max{ it.size() } // one of 'elephant' or 'anaconda'
           assert longestName.size() == 8

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine the correct ordering
      Returns:
        an item from the Iterable having the maximum value returned by calling the supplied closure with that item as parameter or null for an empty Iterable
      Since:
        2.2.0

    - #### <T> public T min()

      Adds min() method to Collection objects.

          assert 2 == [4,2,5].min()

      Returns:
        the minimum value
      See Also:
        min(Iterator)
      Since:
        1.0

    - #### <T> public T min(Comparator<? super T> comparator)

      Selects the minimum value found in the Iterable using the given comparator.

          assert "hi" == ["hello","hi","hey"].min( { a, b -> a.length() <=> b.length() } as Comparator )

      Parameters:
        `comparator` - a Comparator
      Returns:
        the minimum value or null for an empty Iterable
      See Also:
        min(Iterator, java.util.Comparator)
      Since:
        2.2.0

    - #### <T> public T min(Closure closure)

      Selects the item in the iterable which when passed as a parameter to the supplied closure returns the minimum value. A null return value represents the least possible return value. If more than one item has the minimum value, an arbitrary choice is made between the items having the minimum value.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

           assert "hi" == ["hello","hi","hey"].min { it.length() }

           def lastDigit = { a, b -> a % 10 <=> b % 10 }
           assert [19, 55, 91].min(lastDigit) == 91

           def pets = ['dog', 'cat', 'anaconda']
           def shortestName = pets.min{ it.size() } // one of 'dog' or 'cat'
           assert shortestName.size() == 3

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine the correct ordering
      Returns:
        an item from the Iterable having the minimum value returned by calling the supplied closure with that item as parameter or null for an empty Iterable
      See Also:
        min(Iterator)
      Since:
        1.0

    - #### <T> public Collection<T> minus(Iterable<?> removeMe)

      Create a new Collection composed of the elements of the first Iterable minus every occurrence of elements of the given Iterable.

           assert [1, "a", true, true, false, 5.3] - [true, 5.3] == [1, "a", false]

      Parameters:
        `removeMe` - the elements to exclude
      Returns:
        a new Collection
      Since:
        2.4.0

    - #### <T> public Collection<T> minus(Iterable<?> removeMe, Closure condition)

      Create a new Collection composed of the elements of the first Iterable minus every matching occurrence as determined by the condition closure of elements of the given Iterable.

           assert ['a', 'B', 'c', 'D', 'E'].minus(['b', 'C', 'D']) { it.toLowerCase() } == ['a', 'E']

      Parameters:
        `removeMe` - the elements to exclude
        `condition` - a Closure used to determine uniqueness
      Returns:
        a new Collection
      Since:
        4.0.0

    - #### <T> public Collection<T> minus(Iterable<?> removeMe, Comparator<? super T> comparator)

      Create a new Collection composed of the elements of the first Iterable minus every matching occurrence as determined by the condition comparator of elements of the given Iterable.

           List<String> one = ['a', 'B', 'c', 'D', 'E'], two = ['b', 'C', 'D']
           def sub = one.minus(two, Comparator.comparing(String::toLowerCase))
           assert sub == ['a', 'E']

      Parameters:
        `removeMe` - the elements to exclude
        `comparator` - a Comparator
      Returns:
        a new Collection
      Since:
        4.0.0

    - #### <T> public Collection<T> minus(Object removeMe)

      Create a new Collection composed of the elements of the first Iterable minus every occurrence of the given element to remove.

          assert ["a", 5, 5, true] - 5 == ["a", true]

      Parameters:
        `removeMe` - an element to exclude
      Returns:
        a new Collection
      Since:
        2.4.0

    - #### <T> public Collection<T> multiply(Number factor)

      Create a Collection composed of the elements of this Iterable, repeated a certain number of times. Note that for non-primitive elements, multiple references to the same instance will be added.

          assert [1,2,3,1,2,3] == [1,2,3] * 2

      Note: if the Iterable happens to not support duplicates, e.g. a Set, then the method will effectively return a Collection with a single copy of the Iterable's items.
      Parameters:
        `factor` - the number of times to append
      Returns:
        the multiplied Collection
      Since:
        2.4.0

    - #### <T> public Set<List<T>> permutations()

      Finds all permutations of an iterable.

      Example usage:

          def result = [1, 2, 3].permutations()
           assert result == [[3, 2, 1], [3, 1, 2], [1, 3, 2], [2, 3, 1], [2, 1, 3], [1, 2, 3]] as Set

      Returns:
        the permutations from the list
      Since:
        1.7.0

    - #### <T, V> public List<V> permutations(Closure<V> function)

      Finds all permutations of an iterable, applies a function to each permutation and collects the result into a list.

      Example usage:

          Set result = [1, 2, 3].permutations { it.collect { v -> 2*v }}
           assert result == [[6, 4, 2], [6, 2, 4], [2, 6, 4], [4, 6, 2], [4, 2, 6], [2, 4, 6]] as Set

      Parameters:
        `function` - the function to apply on each permutation
      Returns:
        the list of results of the application of the function on each permutation
      Since:
        2.2.0

    - #### <T> public Collection<T> plus(Iterable<T> right)

      Create a Collection as a union of two iterables. If the left iterable is a Set, then the returned collection will be a Set otherwise a List. This operation will always create a new object for the result, while the operands remain unchanged.

          assert [1,2,3,4] == [1,2] + [3,4]

      Parameters:
        `right` - the right Iterable
      Returns:
        the merged Collection
      Since:
        2.4.0

    - #### <T> public Collection<T> plus(T right)

      Create a collection as a union of an Iterable and an Object. If the iterable is a Set, then the returned collection will be a Set otherwise a List. This operation will always create a new object for the result, while the operands remain unchanged.

          assert [1,2,3] == [1,2] + 3

      Parameters:
        `right` - an object to add/append
      Returns:
        the resulting Collection
      Since:
        2.4.0

    - #### <T> public Collection<T> repeat(int count)

      Repeat the elements from an iterable. An alias for multiply.

           assert ['a', 42].repeat(2) == ['a', 42, 'a', 42]

      Parameters:
        `count` - the (non-negative) number of times to repeat
      Returns:
        a collection containing the repeated elements
      Since:
        5.0.0

    - #### <T> public Iterator<T> repeat()

      Repeat the elements from an iterable infinitely.

           assert ['a', 42].repeat().take(5).toList() == ['a', 42, 'a', 42, 'a']

      Returns:
        an iterator containing the (infinite) repeated elements
      Since:
        5.0.0

    - #### public int size()

      Provide the standard Groovy `size()` method for `Iterable`.

           def items = [1, 2, 3]
           def iterable = { [ hasNext:{ !items.isEmpty() }, next:{ items.pop() } ] as Iterator } as Iterable
           assert iterable.size() == 3

      Returns:
        the length of the Iterable
      Since:
        2.3.8

    - #### <T> public List<T> sort()

      Sorts the Collection. Assumes that the collection items are comparable and uses their natural ordering to determine the resulting order. If the Collection is a List, it is sorted in place and returned. Otherwise, the elements are first placed into a new list which is then sorted and returned - leaving the original Collection unchanged.

          assert [1,2,3] == [3,1,2].sort()

      Returns:
        the sorted Iterable as a List
      See Also:
        sort(Iterable, boolean)
      Since:
        2.2.0

    - #### <T> public List<T> sort(boolean mutate)

      Sorts the Iterable. Assumes that the Iterable items are comparable and uses their natural ordering to determine the resulting order. If the Iterable is a List and mutate is true, it is sorted in place and returned. Otherwise, the elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

          assert [1,2,3] == [3,1,2].sort()

           def orig = [1, 3, 2]
           def sorted = orig.sort(false)
           assert orig == [1, 3, 2]
           assert sorted == [1, 2, 3]

      Parameters:
        `mutate` - false will always cause a new list to be created, true will mutate lists in place
      Returns:
        the sorted iterable as a List
      Since:
        2.2.0

    - #### <T> public List<T> sort(boolean mutate, Comparator<? super T> comparator)

      Sorts the Iterable using the given Comparator. If the Iterable is a List and mutate is true, it is sorted in place and returned. Otherwise, the elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

           assert ["hi","hey","hello"] == ["hello","hi","hey"].sort(false, { a, b -> a.length() <=> b.length() } as Comparator )

           def orig = ["hello","hi","Hey"]
           def sorted = orig.sort(false, String.CASE_INSENSITIVE_ORDER)
           assert orig == ["hello","hi","Hey"]
           assert sorted == ["hello","Hey","hi"]

      Parameters:
        `mutate` - false causes a new list to be created, true will mutate lists in place
        `comparator` - a Comparator used for the comparison
      Returns:
        a sorted List
      Since:
        2.2.0

    - #### <T> public List<T> sort(Closure closure)

      Sorts this Iterable using the given Closure to determine the correct ordering. If the Iterable is a List, it is sorted in place and returned. Otherwise, the elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

      If the Closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { it.length() }

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { a, b -> a.length() <=> b.length() }

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine the correct ordering
      Returns:
        a newly created sorted List
      See Also:
        sort(Iterable, boolean, Closure)
      Since:
        2.2.0

    - #### <T> public List<T> sort(boolean mutate, Closure closure)

      Sorts this Iterable using the given Closure to determine the correct ordering. If the Iterable is a List and mutate is true, it is sorted in place and returned. Otherwise, the elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

      If the closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { it.length() }

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { a, b -> a.length() <=> b.length() }

           def orig = ["hello","hi","Hey"]
           def sorted = orig.sort(false) { it.toUpperCase() }
           assert orig == ["hello","hi","Hey"]
           assert sorted == ["hello","Hey","hi"]

      Parameters:
        `mutate` - false will always cause a new list to be created, true will mutate lists in place
        `closure` - a 1 or 2 arg Closure used to determine the correct ordering
      Returns:
        a newly created sorted List
      Since:
        2.2.0

    - #### <T> public Stream<T> stream()

      Returns a sequential Stream with the specified element(s) as its source.

           class Items implements Iterable {
             Iterator<String> iterator() {
               ['one', 'two'].iterator()
             }
           }
           def items = new Items()
           assert items.stream().toList() == ['one', 'two']

      Since:
        3.0.0

    - #### public Object sum()

      Sums the items in an Iterable. This is equivalent to invoking the "plus" method on all items in the Iterable.

          assert 1+2+3+4 == [1,2,3,4].sum()

      Returns:
        The sum of all the items
      See Also:
        sum(Iterator)
      Since:
        2.2.0

    - #### public Object sum(Object initialValue)

      Sums the items in an Iterable, adding the result to some initial value.

           assert 5+1+2+3+4 == [1,2,3,4].sum(5)

      Parameters:
        `initialValue` - the items in the collection will be summed to this initial value
      Returns:
        The sum of all the items.
      See Also:
        sum(Iterator, Object)
      Since:
        2.2.0

    - #### <T> public Object sum(Closure closure)

      Sums the result of applying a closure to each item of an Iterable. `coll.sum(closure)` is equivalent to: `coll.collect(closure).sum()`.

          assert 4+6+10+12 == [2,3,5,6].sum { it * 2 }

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
      Returns:
        The sum of the values returned by applying the closure to each item of the Iterable.
      Since:
        2.2.0

    - #### <T> public Object sum(Object initialValue, Closure closure)

      Sums the result of applying a closure to each item of an Iterable to some initial value. `iter.sum(initVal, closure)` is equivalent to: `iter.collect(closure).sum(initVal)`.

          assert 50+4+6+10+12 == [2,3,5,6].sum(50) { it * 2 }

      Parameters:
        `closure` - a single parameter closure that returns a (typically) numeric value.
        `initialValue` - the closure results will be summed to this initial value
      Returns:
        The sum of the values returned by applying the closure to each item of the collection.
      Since:
        1.5.0

    - #### <T> public Collection<T> tail()

      Returns the items from the Iterable excluding the first item.

           def list = [3, 4, 2]
           assert list.tail() == [4, 2]
           assert list == [3, 4, 2]

      throws:
        NoSuchElementException if you try to access tail() for an empty Iterable
      Returns:
        a collection without its first element
      Since:
        2.4.0

    - #### <T> public List<List<T>> tails()

      Calculates the tail values of this Iterable: the first value will be this list of all items from the iterable and the final one will be an empty list, with the intervening values the results of successive applications of tail on the items.

           assert [1, 2, 3, 4].tails() == [[1, 2, 3, 4], [2, 3, 4], [3, 4], [4], []]

      Returns:
        a List of the tail values from the given Iterable
      Since:
        2.5.0

    - #### <T> public Collection<T> take(int num)

      Returns the first `num` elements from the head of this Iterable.

           def strings = [ 'a', 'b', 'c' ]
           assert strings.take( 0 ) == []
           assert strings.take( 2 ) == [ 'a', 'b' ]
           assert strings.take( 5 ) == [ 'a', 'b', 'c' ]

           class AbcIterable implements Iterable {
               Iterator iterator() { "abc".iterator() }
           }
           def abc = new AbcIterable()
           assert abc.take(0) == []
           assert abc.take(1) == ['a']
           assert abc.take(3) == ['a', 'b', 'c']
           assert abc.take(5) == ['a', 'b', 'c']

      Parameters:
        `num` - the number of elements to take from this Iterable
      Returns:
        a Collection consisting of the first `num` elements from this Iterable, or else all the elements from the Iterable if it has less than `num` elements.
      Since:
        1.8.7

    - #### <T> public Collection<T> takeRight(int num)

      Returns the last `num` elements from the tail of this Iterable.

           def strings = [ 'a', 'b', 'c' ]
           assert strings.takeRight( 0 ) == []
           assert strings.takeRight( 2 ) == [ 'b', 'c' ]
           assert strings.takeRight( 5 ) == [ 'a', 'b', 'c' ]

           class AbcIterable implements Iterable {
               Iterator iterator() { "abc".iterator() }
           }
           def abc = new AbcIterable()
           assert abc.takeRight(0) == []
           assert abc.takeRight(1) == ['c']
           assert abc.takeRight(3) == ['a', 'b', 'c']
           assert abc.takeRight(5) == ['a', 'b', 'c']

      Parameters:
        `num` - the number of elements to take from this Iterable
      Returns:
        a Collection consisting of the last `num` elements from this Iterable, or else all the elements from the Iterable if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public Collection<T> takeWhile(Closure condition)

      Returns a Collection containing the longest prefix of the elements from this Iterable where each element passed to the given closure evaluates to true.

           class AbcIterable implements Iterable {
               Iterator iterator() { "abc".iterator() }
           }
           def abc = new AbcIterable()
           assert abc.takeWhile{ it < 'b' } == ['a']
           assert abc.takeWhile{ it <= 'b' } == ['a', 'b']

      Parameters:
        `condition` - the closure that must evaluate to true to continue taking elements
      Returns:
        a Collection containing a prefix of the elements from the given Iterable where each element passed to the given closure evaluates to true
      Since:
        1.8.7

    - #### <T> public Collection<T> takeWhile(Predicate<? super T> condition)

      Returns the longest prefix of an Iterable where each element passes the given predicate. A "fat-free" variant of Iterable.takeWhile accepting a Predicate.

           assert (1..5).takeWhile(n -> n < 3) == [1, 2]

      Parameters:
        `condition` - the predicate that must evaluate to true to continue taking elements
      Returns:
        a prefix of the given Iterable where each element passes the given predicate
      Since:
        6.0.0

    - #### <T> public List<T> toImmutableList()

      Convert an Iterable to an immutable List. The Iterable's iterator will become exhausted of elements after making this conversion.

      Returns:
        an immutable List of the elements from the Iterable
      Since:
        6.0.0

    - #### <T> public Set<T> toImmutableSet()

      Convert an Iterable to an immutable Set. The Iterable's iterator will become exhausted of elements after making this conversion.

      Returns:
        an immutable Set of the elements from the Iterable
      Since:
        6.0.0

    - #### <T> public List<T> toList()

      Convert an Iterable to a List. The Iterable's iterator will become exhausted of elements after making this conversion.

      Example usage:

          def x = [1,2,3] as HashSet
           assert x.class == HashSet
           assert x.toList() instanceof List

      Returns:
        a List
      Since:
        1.8.7

    - #### <T> public Set<T> toSet()

      Convert an Iterable to a Set. Always returns a new Set even if the Iterable is already a Set.

      Example usage:

           def result = [1, 2, 2, 2, 3].toSet()
           assert result instanceof Set
           assert result == [1, 2, 3] as Set

      Returns:
        a Set
      Since:
        2.4.0

    - #### <T> public List<T> toSorted()

      Sorts the Iterable. Assumes that the Iterable elements are comparable and uses a NumberAwareComparator to determine the resulting order. `NumberAwareComparator` has special treatment for numbers but otherwise uses the natural ordering of the Iterable elements. The elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

           def orig = [1, 3, 2]
           def sorted = orig.toSorted()
           assert orig == [1, 3, 2]
           assert sorted == [1, 2, 3]

      Returns:
        the sorted iterable as a List
      See Also:
        toSorted(Iterable, Comparator)
      Since:
        2.4.0

    - #### <T> public List<T> toSorted(Comparator<? super T> comparator)

      Sorts the Iterable using the given Comparator. The elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

           def orig = ["hello","hi","Hey"]
           def sorted = orig.toSorted(String.CASE_INSENSITIVE_ORDER)
           assert orig == ["hello","hi","Hey"]
           assert sorted == ["hello","Hey","hi"]

      Parameters:
        `comparator` - a Comparator used for the comparison
      Returns:
        a sorted List
      Since:
        2.4.0

    - #### <T> public List<T> toSorted(Closure closure)

      Sorts this Iterable using the given Closure to determine the correct ordering. The elements are first placed into a new list which is then sorted and returned - leaving the original Iterable unchanged.

      If the Closure has two parameters it is used like a traditional Comparator. I.e. it should compare its two parameters for order, returning a negative integer, zero, or a positive integer when the first parameter is less than, equal to, or greater than the second respectively. Otherwise, the Closure is assumed to take a single parameter and return a Comparable (typically an Integer) which is then used for further comparison.

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { it.length() }

          assert ["hi","hey","hello"] == ["hello","hi","hey"].sort { a, b -> a.length() <=> b.length() }

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine the correct ordering
      Returns:
        a newly created sorted List
      See Also:
        toSorted(Iterable, Comparator)
      Since:
        2.4.0

    - #### public SpreadMap toSpreadMap()

      Creates a spreadable map from this iterable.

      Returns:
        a newly created SpreadMap
      See Also:
        SpreadMap.SpreadMap
        toSpreadMap(java.util.Map)
      Since:
        2.4.0

    - #### <T> public Collection<T> toUnique(Comparator<? super T> comparator)

      Returns a Collection containing the items from the Iterable but with duplicates removed. The items in the Iterable are compared by the given Comparator. For each duplicate, the first member which is returned from the Iterable is retained, but all other ones are removed.

           class Person {
               def fname, lname
               String toString() {
                   return fname + " " + lname
               }
           }

           class PersonComparator implements Comparator {
               int compare(Object o1, Object o2) {
                   Person p1 = (Person) o1
                   Person p2 = (Person) o2
                   if (p1.lname != p2.lname)
                       return p1.lname.compareTo(p2.lname)
                   else
                       return p1.fname.compareTo(p2.fname)
               }

               boolean equals(Object obj) {
                   return this.equals(obj)
               }
           }

           Person a = new Person(fname:"John", lname:"Taylor")
           Person b = new Person(fname:"Clark", lname:"Taylor")
           Person c = new Person(fname:"Tom", lname:"Cruz")
           Person d = new Person(fname:"Clark", lname:"Taylor")

           def list = [a, b, c, d]
           List list2 = list.toUnique(new PersonComparator())
           assert list2 == [a, b, c] && list == [a, b, c, d]

      Parameters:
        `comparator` - a Comparator used to determine unique (equal) items If `null`, the Comparable natural ordering of the elements will be used.
      Returns:
        the Collection of non-duplicate items
      Since:
        2.4.0

    - #### <T> public Collection<T> toUnique()

      Returns a Collection containing the items from the Iterable but with duplicates removed using the natural ordering of the items to determine uniqueness.

           String[] letters = ['c', 'a', 't', 's', 'a', 't', 'h', 'a', 't']
           String[] expected = ['c', 'a', 't', 's', 'h']
           assert letters.toUnique() == expected

      Returns:
        the Collection of non-duplicate items
      Since:
        2.4.0

    - #### <T> public Collection<T> toUnique(Closure condition)

      Returns a Collection containing the items from the Iterable but with duplicates removed. The items in the Iterable are compared by the given Closure condition. For each duplicate, the first member which is returned from the Iterable is retained, but all other ones are removed.

      If the closure takes a single parameter, each element from the Iterable will be passed to the closure. The closure should return a value used for comparison (either using Comparable.compareTo or Object.equals). If the closure takes two parameters, two items from the Iterable will be passed as arguments, and the closure should return an int value (with 0 indicating the items are not unique).

           class Person {
               def fname, lname
               String toString() {
                   return fname + " " + lname
               }
           }

           Person a = new Person(fname:"John", lname:"Taylor")
           Person b = new Person(fname:"Clark", lname:"Taylor")
           Person c = new Person(fname:"Tom", lname:"Cruz")
           Person d = new Person(fname:"Clark", lname:"Taylor")

           def list = [a, b, c, d]
           def list2 = list.toUnique{ p1, p2 -> p1.lname != p2.lname ? p1.lname <=> p2.lname : p1.fname <=> p2.fname }
           assert( list2 == [a, b, c] && list == [a, b, c, d] )
           def list3 = list.toUnique{ it.toString() }
           assert( list3 == [a, b, c] && list == [a, b, c, d] )

      Parameters:
        `condition` - a Closure used to determine unique items
      Returns:
        a new Collection
      See Also:
        toUnique(Iterable, Comparator)
      Since:
        2.4.0

    - #### <T> public Collection<T> union(Iterable<T> right)

      Create a Collection composed of the union of both iterables. Any elements that exist in either iterables are added to the resultant collection, such that no elements are duplicated in the resultant collection. For iterables of custom objects; the objects should implement java.lang.Comparable

           assert [1,2,3,4,5,6,7,8] == [1,2,3,4,5].union([4,5,6,7,8])

      By default, Groovy uses a NumberAwareComparator when determining if an element already exists in the resultant collection.
      Parameters:
        `right` - an Iterable
      Returns:
        a Collection as a union of both iterables
      See Also:
        union(Iterable, Iterable, Comparator)
      Since:
        5.0.0

    - #### <T> public Collection<T> union(Iterable<T> right, Comparator<? super T> comparator)

      Create a Collection composed of the union of both iterables. Any elements that exist in either iterables are added to the resultant collection, such that no elements are duplicated in the resultant collection. For iterables of custom objects; the objects should implement java.lang.Comparable

           assert [1,2,3,4,5,6] == [1,2,3,4].union([3,4,5,6], Comparator.naturalOrder())

      Parameters:
        `right` - an Iterable
        `comparator` - a Comparator
      Returns:
        a Collection as a union of both iterables
      Since:
        5.0.0

    - #### <T> public Collection<T> union(Iterable<T> right, Closure condition)

      Create a Collection composed of the union of both iterables. Elements from the first iterable and second iterable are added to the result if the elements are not already in the result (according to the comparator closure). If the closure takes a single parameter, the argument passed will be each element, and the closure should return a value used for comparison (either using Comparable.compareTo or Object.equals). If the closure takes two parameters, two items from the Iterator will be passed as arguments, and the closure should return an int value (with 0 indicating the items are deemed equal).

           def one = ['a', 'B', 'c', 'd']
           def two = ['b', 'C', 'd', 'e']
           def compareIgnoreCase = { it.toLowerCase() }
           assert one.union(two, compareIgnoreCase) == ['a', 'B', 'c', 'd', 'e']
           assert two.union(one, compareIgnoreCase) == ['b', 'C', 'd', 'e', 'a']

      Parameters:
        `right` - an Iterable
        `condition` - a Closure used to determine unique items
      Returns:
        a Collection as a union of both iterables
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedKeys(Map<K, V> collector, Function<? super V, K> keyTransform)

      Transform Iterable elements into Map entries with values unchanged and keys transformed using the supplied function. The supplied map is used as the destination for transformed entries.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           def firstLetter = s -> s[0]
           assert languages.withCollectedKeys([C:'Clojure'], firstLetter) ==
               [C:'Clojure', G:'Groovy', J:'Java', K:'Kotlin', S:'Scala']

      This method is a convenience method for Iterable.collectEntries with the `valueTransform` replaced by `Function.identity()` or {Closure.IDENTITY}.
      Parameters:
        `collector` - the Map into which the transformed entries are put
        `keyTransform` - a function for transforming Iterator elements into keys
      Returns:
        the collector with all transformed values added to it
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedKeys(Function<? super V, K> keyTransform)

      Transform Iterable elements into Map entries with values unchanged and keys transformed using the supplied function.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           def firstLetter = s -> s[0]
           assert languages.withCollectedKeys(firstLetter) ==
               [G:'Groovy', J:'Java', K:'Kotlin', S:'Scala']

      This method is a convenience method for Iterable.collectEntries with the `valueTransform` replaced by `Function.identity()` or {Closure.IDENTITY}.
      Parameters:
        `keyTransform` - a function for transforming Iterator elements into keys
      Returns:
        the collector with all transformed values added to it
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedValues(Map<K, V> collector, Function<? super K, V> valueTransform)

      Transform Iterable elements into Map entries with keys unchanged and values transformed using the supplied function. The supplied collector map is used as the destination for transformed entries.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           assert languages.withCollectedValues([Clojure:7], String::size) ==
               [Clojure:7, Groovy:6, Java:4, Kotlin:6, Scala:5]

      This method is a convenience method for Iterable.collectEntries with the `keyTransform` replaced by `Function.identity()` or {Closure.IDENTITY}.
      Parameters:
        `collector` - the Map into which the transformed entries are put
        `valueTransform` - a function for transforming Iterable elements into values
      Returns:
        the collector with all transformed values added to it
      Since:
        5.0.0

    - #### <K, V> public Map<K, V> withCollectedValues(Function<? super K, V> valueTransform)

      Transform Iterable elements into Map entries with keys unchanged and values transformed using the supplied function.

           def languages = ['Groovy', 'Java', 'Kotlin', 'Scala']
           assert languages.withCollectedValues(String::size) ==
               [Groovy:6, Java:4, Kotlin:6, Scala:5]

      This method is a convenience method for Iterable.collectEntries with the `keyTransform` replaced by `Function.identity()` or {Closure.IDENTITY}.
      Parameters:
        `valueTransform` - a function for transforming Iterable elements into values
      Returns:
        a Map of the transformed entries
      Since:
        5.0.0

    - #### <E> public List<Tuple2<E, Integer>> withIndex()

      Zips an Iterable with indices in (value, index) order.

      Example usage:

           assert [["a", 0], ["b", 1]] == ["a", "b"].withIndex()
           assert ["0: a", "1: b"] == ["a", "b"].withIndex().collect { str, idx -> "$idx: $str" }

      Returns:
        a zipped list with indices
      See Also:
        indexed(Iterable)
      Since:
        2.4.0

    - #### <E> public List<Tuple2<E, Integer>> withIndex(int offset)

      Zips an Iterable with indices in (value, index) order.

      Example usage:

           assert [["a", 5], ["b", 6]] == ["a", "b"].withIndex(5)
           assert ["1: a", "2: b"] == ["a", "b"].withIndex(1).collect { str, idx -> "$idx: $str" }

      Parameters:
        `offset` - an index to start from
      Returns:
        a zipped list with indices
      See Also:
        indexed(Iterable, int)
      Since:
        2.4.0

    - #### <U, V> public List<Tuple2<U, V>> zip(Iterable<V> other)

      A list of all the pairs from two Iterables. If the iterables are of different sizes, the result will have the same size as the shorter one.

      Example:

           def one = ['cat', 'spider']
           def two = ['fish', 'monkey']
           assert ['catfish', 'spidermonkey'] == one.zip(two).collect{ a, b -> a + b }
           assert [one, two].transpose() == one.zip(two).toList()

      Parameters:
        `other` - another Iterable
      Returns:
        a list of all the pairs from self and other
      See Also:
        for zipping more than two lists
      Since:
        5.0.0

    - #### <U, V> public Collection<Tuple2<U, V>> zipAll(Iterable<V> other, U selfDefault, V otherDefault)

      A collection of all the pairs of two Iterables of potentially different size. If the iterables are of different sizes, the result will have the same size as the longer one with values completed using the provided default.

      Example:

           def ab = ['a', 'b']
           def abcd = 'a'..'d'
           def nums = 1..3
           assert ['a1', 'b2', 'unknown3'] == ab.zipAll(nums, 'unknown', 0).collect{ a, b -> a + b }
           assert ['a1', 'b2', 'c3', 'd0'] == abcd.zipAll(nums, 'unknown', 0).collect{ a, b -> a + b }

      Parameters:
        `other` - another Iterable
      Returns:
        a collection of all the pairs from self and other
      Since:
        5.0.0

    - #### <T> public List<Tuple2<T, T>> zipWithNext()

      Returns a list of all the successive adjacent pairs from this Iterable (a sliding window of size 2, step 1). The result has one fewer element than the input; an empty or single-element Iterable yields an empty list. Each pair is a Tuple2, which is also a `List`.

      Example:

           assert [1, 2, 3, 4].zipWithNext() == [[1, 2], [2, 3], [3, 4]]
           assert [].zipWithNext() == []
           assert [42].zipWithNext() == []

      Returns:
        a list of the adjacent pairs
      Since:
        6.0.0

    - #### <T, R> public List<R> zipWithNext(BiFunction<? super T, ? super T, ? extends R> combiner)

      Applies the combiner to each successive adjacent pair from this Iterable, returning the list of results. The result has one fewer element than the input; an empty or single-element Iterable yields an empty list.

      Example:

           assert [1, 2, 3, 4].zipWithNext{ a, b -> b - a } == [1, 1, 1]
           assert [3, 1, 4, 1, 5].zipWithNext{ a, b -> a <= b } == [false, true, false, true]
           assert 'abcd'.toList().zipWithNext{ a, b -> a + b } == ['ab', 'bc', 'cd']

      Parameters:
        `combiner` - a function applied to each adjacent pair
      Returns:
        a list of the combined adjacent pairs
      Since:
        6.0.0