Iterable (Groovy JDK enhancements)

Package: java.lang

## Interface Iterable

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `boolean` | `any(Closure closure)` Iterates over the contents of an iterable, and checks whether a predicate is valid for at least one element.
    `Collection` | `asCollection()` Converts this Iterable to a Collection.
    `List` | `asList()` Converts this Iterable to a List.
    `List` | `collate(int size)` Collates this iterable into sub-lists of length `size`.
    `List` | `collate(int size, boolean keepRemainder)` Collates this iterable into sub-lists of length `size`.
    `List` | `collate(int size, int step)` Collates this iterable into sub-lists of length `size` stepping through the code `step` elements for each subList.
    `List` | `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.
    `Map` | `collectEntries()` A variant of collectEntries for Iterable objects using the identity closure as the transform.
    `Map` | `collectEntries(Closure transform)` Iterates through this Iterable transforming each item using the `transform` closure and returning a map of the resulting transformed entries.
    `Map` | `collectEntries(Map collector)` A variant of collectEntries for Iterables using the identity closure as the transform and a supplied map as the destination of transformed entries.
    `Map` | `collectEntries(Map 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 of the transformed entries added to it.
    `List` | `collectMany(Closure projection)` Projects each item from a source Iterable to a collection and concatenates (flattens) the resulting collections into a single list.
    `Collection` | `collectMany(Collection collector, Closure projection)` Projects each item from a source collection to a result collection and concatenates (flattens) the resulting collections adding them into the `collector`.
    `List` | `collectNested(Closure transform)` Recursively iterates through this Iterable transforming each non-Collection value into a new value using the closure as a transformer.
    `Collection` | `collectNested(Collection collector, Closure transform)` Recursively iterates through this Iterable transforming each non-Collection value into a new value using the `transform` closure.
    `List` | `combinations()` Adds GroovyCollections#combinations(Iterable) as a method on Iterables.
    `List` | `combinations(Closure function)` Adds GroovyCollections#combinations(Iterable, Closure) as a method on collections.
    `boolean` | `contains(Object item)` Returns `true` if this iterable contains the item.
    `boolean` | `containsAll(Object[] items)` Returns `true` if this iterable contains all of the elements in the specified array.
    `Number` | `count(Closure closure)` Counts the number of occurrences which satisfy the given closure from inside this Iterable.
    `Number` | `count(Object value)` Counts the number of occurrences of the given value inside this Iterable.
    `Map` | `countBy(Closure closure)` Sorts all collection members into groups determined by the supplied mapping closure and counts the group size.
    `boolean` | `disjoint(Iterable right)` Returns `true` if the intersection of two iterables is empty.
    `Collection` | `drop(int num)` Drops the given number of elements from the head of this Iterable.
    `Collection` | `dropRight(int num)` Drops the given number of elements from the tail of this Iterable.
    `Collection` | `dropWhile(Closure condition)` Returns a suffix of this Iterable where elements are dropped from the front while the given closure evaluates to true.
    `Iterable` | `each(Closure closure)` Iterates through an Iterable, passing each item to the given closure.
    `void` | `eachCombination(Closure function)` Applies a function on each combination of the input lists.
    `Iterator` | `eachPermutation(Closure closure)` Iterates over all permutations of a collection, running a closure for each iteration.
    `Iterable` | `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.
    `boolean` | `every(Closure closure)` Used to determine if the given predicate closure is valid (i.e. returns `true` for all items in this iterable).
    `Collection` | `findResults(Closure filteringTransform)` Iterates through the Iterable transforming items using the supplied closure and collecting any non-null results.
    `Object` | `first()` Returns the first item from the Iterable.
    `Collection` | `flatten()` Flatten an Iterable.
    `Collection` | `flatten(Closure flattenUsing)` Flatten an Iterable.
    `Object` | `getAt(int idx)` Support the subscript operator for an Iterable.
    `Map` | `groupBy(Closure closure)` Sorts all Iterable members into groups determined by the supplied mapping closure.
    `Map` | `groupBy(Object closures)` Sorts all Iterable members into (sub)groups determined by the supplied mapping closures.
    `Map` | `groupBy(List closures)` Sorts all Iterable members into (sub)groups determined by the supplied mapping closures.
    `Object` | `head()` Returns the first item from the Iterable.
    `Map` | `indexed()` Zips an Iterable with indices in (index, value) order.
    `Map` | `indexed(int offset)` Zips an Iterable with indices in (index, value) order.
    `Collection` | `init()` Returns the items from the Iterable excluding the last item.
    `Collection` | `intersect(Iterable right)` Create a Collection composed of the intersection of both iterables.
    `String` | `join(String separator)` Concatenates the `toString()` representation of each item in this Iterable, with the given String as a separator between each item.
    `Object` | `last()` Returns the last item from the Iterable.
    `Object` | `max()` Adds max() method to Iterable objects.
    `Object` | `max(Closure closure)` Selects the item in the iterable which when passed as a parameter to the supplied closure returns the maximum value.
    `Object` | `max(Comparator comparator)` Selects the maximum value found in the Iterable using the given comparator.
    `Object` | `min()` Adds min() method to Collection objects.
    `Object` | `min(Closure closure)` Selects the item in the iterable which when passed as a parameter to the supplied closure returns the minimum value.
    `Object` | `min(Comparator comparator)` Selects the minimum value found in the Iterable using the given comparator.
    `Collection` | `minus(Iterable removeMe)` Create a new Collection composed of the elements of the first Iterable minus every occurrence of elements of the given Iterable.
    `Collection` | `minus(Object removeMe)` Create a new Collection composed of the elements of the first Iterable minus every occurrence of the given element to remove.
    `Collection` | `multiply(Number factor)` Create a Collection composed of the elements of this Iterable, repeated a certain number of times.
    `Set` | `permutations()` Finds all permutations of an iterable.
    `List` | `permutations(Closure function)` Finds all permutations of an iterable, applies a function to each permutation and collects the result into a list.
    `Collection` | `plus(Iterable right)` Create a Collection as a union of two iterables.
    `Collection` | `plus(Object right)` Create a collection as a union of an Iterable and an Object.
    `int` | `size()` Provide the standard Groovy `size()` method for `Iterable`.
    `List` | `sort()` Sorts the Collection.
    `List` | `sort(boolean mutate)` Sorts the Iterable.
    `List` | `sort(boolean mutate, Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `List` | `sort(boolean mutate, Comparator comparator)` Sorts the Iterable using the given Comparator.
    `List` | `sort(Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `Object` | `sum()` Sums the items in an Iterable.
    `Object` | `sum(Closure closure)` Sums the result of apply a closure to each item of an Iterable.
    `Object` | `sum(Object initialValue)` Sums the items in an Iterable, adding the result to some initial value.
    `Object` | `sum(Object initialValue, Closure closure)` Sums the result of applying a closure to each item of an Iterable to some initial value.
    `Collection` | `tail()` Returns the items from the Iterable excluding the first item.
    `Collection` | `take(int num)` Returns the first `num` elements from the head of this Iterable.
    `Collection` | `takeRight(int num)` Returns the last `num` elements from the tail of this Iterable.
    `Collection` | `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.
    `List` | `toList()` Convert an Iterable to a List.
    `Set` | `toSet()` Convert an Iterable to a Set.
    `List` | `toSorted()` Sorts the Iterable.
    `List` | `toSorted(Closure closure)` Sorts this Iterable using the given Closure to determine the correct ordering.
    `List` | `toSorted(Comparator comparator)` Sorts the Iterable using the given Comparator.
    `SpreadMap` | `toSpreadMap()` Creates a spreadable map from this iterable.
    `Collection` | `toUnique()` Returns a Collection containing the items from the Iterable but with duplicates removed using the natural ordering of the items to determine uniqueness.
    `Collection` | `toUnique(Closure condition)` Returns a Collection containing the items from the Iterable but with duplicates removed.
    `Collection` | `toUnique(Comparator comparator)` Returns a Collection containing the items from the Iterable but with duplicates removed.
    `List` | `withIndex()` Zips an Iterable with indices in (value, index) order.
    `List` | `withIndex(int offset)` Zips an Iterable with indices in (value, index) order.

- - ### Methods Detail

    - #### public boolean any(Closure closure)

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

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

    - #### public Collection asCollection()

      Converts this Iterable to a Collection. Returns the original Iterable 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

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

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

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

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

    - #### public List 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 ] ]

      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

    - #### public Map 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
      Since:
        1.8.7
      See Also:
        Iterator#collectEntries()

    - #### public Map 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
      Since:
        1.8.7
      See Also:
        Iterator#collectEntries(Closure)

    - #### public Map collectEntries(Map 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
      Since:
        1.8.7
      See Also:
        Iterator#collectEntries(Map)

    - #### public Map collectEntries(Map 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 of 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
      Since:
        1.8.7
      See Also:
        Iterator#collectEntries(Map, Closure)

    - #### public List collectMany(Closure 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
      Since:
        2.2.0
      See Also:
        Collection#sum(groovy.lang.Closure)

    - #### public Collection collectMany(Collection collector, Closure 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'] as Set
          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

      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

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

    - #### public Collection collectNested(Collection 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 combinations()

      Adds GroovyCollections#combinations(Iterable) as a method on Iterables.

      Example usage:

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

      Returns:
        a List of the combinations found
      Since:
        2.2.0
      See Also:
        GroovyCollections#combinations(java.lang.Iterable)

    - #### public List combinations(Closure function)

      Adds GroovyCollections#combinations(Iterable, Closure) as a method on collections.

      Example usage:

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

      Parameters:
        `function` - a closure to be called on each combination
      Returns:
        a List of the results of applying the closure to each combinations found
      Since:
        2.2.0
      See Also:
        GroovyCollections#combinations(Iterable)

    - #### 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
      Since:
        2.4.0
      See Also:
        Collection#contains(Object)

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

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

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

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

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

    - #### public Map countBy(Closure 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

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

    - #### public Collection 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 then `num` elements.
      Since:
        1.8.7

    - #### public Collection 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 then `num` elements.
      Since:
        2.4.0

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

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

    - #### 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
      Since:
        2.2.0
      See Also:
        GroovyCollections#combinations(Iterable)

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

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

    - #### public boolean every(Closure closure)

      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:
        `closure` - the closure predicate used for matching
      Returns:
        true if every iteration of the object matches the closure predicate
      Since:
        2.3.0

    - #### public Collection findResults(Closure 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

    - #### public Object 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.
      Returns:
        the first item from the Iterable
      Since:
        1.8.7

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

    - #### public Collection flatten(Closure flattenUsing)

      Flatten an Iterable. This Iterable and any nested arrays or collections have their contents (recursively) added to the new collection. For any non-Array, non-Collection object which represents some sort of collective type, the supplied closure should yield the contained items; otherwise, the closure should just return any element which corresponds to a leaf.

      Parameters:
        `flattenUsing` - a closure to determine how to flatten non-Array, non-Collection elements
      Returns:
        a flattened Collection
      Since:
        1.6.0

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

    - #### public Map groupBy(Closure 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

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

    - #### public Object 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.
      Returns:
        the first item from the Iterable
      Since:
        2.4.0

    - #### public Map 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
      Since:
        2.4.0
      See Also:
        Iterable#withIndex()

    - #### public Map 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
      Since:
        2.4.0
      See Also:
        Iterable#withIndex(int)

    - #### public Collection 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]

      Returns:
        a Collection without its last element
      Since:
        2.4.0

    - #### public Collection intersect(Iterable 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 collection of custom objects; objects should implement java.lang.Comparable

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

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

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

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

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

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

    - #### public Object 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 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.
      Returns:
        the first item from the Iterable
      Since:
        1.8.7

    - #### public Object max()

      Adds max() method to Iterable objects.

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

      Returns:
        the maximum value
      Since:
        2.2.0
      See Also:
        GroovyCollections#max(java.lang.Iterable)

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

    - #### public Object max(Comparator 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
      Since:
        2.2.0

    - #### public Object min()

      Adds min() method to Collection objects.

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

      Returns:
        the minimum value
      Since:
        1.0
      See Also:
        GroovyCollections#min(java.util.Collection)

    - #### public Object 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
      Since:
        1.0

    - #### public Object min(Comparator 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
      Since:
        2.2.0

    - #### public Collection 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` - an Iterable of elements to remove
      Returns:
        a new Collection with the given elements removed
      Since:
        2.4.0

    - #### public Collection 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 remove from the Iterable
      Returns:
        the resulting Collection with the given element removed
      Since:
        2.4.0

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

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

    - #### public List permutations(Closure 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

    - #### public Collection plus(Iterable 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

    - #### public Collection plus(Object 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

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

    - #### public List 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
      Since:
        2.2.0
      See Also:
        Collection#sort(boolean)

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

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

    - #### public List sort(boolean mutate, Comparator 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 will always cause 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

    - #### public List 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
      Since:
        2.2.0
      See Also:
        Collection#sort(boolean, Closure)

    - #### 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 of the items
      Since:
        2.2.0

    - #### public Object sum(Closure closure)

      Sums the result of apply 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 numeric value.
      Returns:
        The sum of the values returned by applying the closure to each item of the Iterable.
      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 of the items.
      Since:
        2.2.0

    - #### public Object sum(Object initialValue, Closure closure)

      Sums the result of applying a closure to each item of an Iterable to some initial value. `coll.sum(initVal, closure)` is equivalent to: `coll.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 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

    - #### public Collection 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]

      Returns:
        a collection without its first element
      Since:
        2.4.0

    - #### public Collection 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 then `num` elements.
      Since:
        1.8.7

    - #### public Collection 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 then `num` elements.
      Since:
        2.4.0

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

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

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

    - #### public List 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
      Since:
        2.4.0
      See Also:
        Iterable#toSorted(Comparator)

    - #### public List 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
      Since:
        2.4.0
      See Also:
        Iterable#toSorted(Comparator)

    - #### public List toSorted(Comparator 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

    - #### public SpreadMap toSpreadMap()

      Creates a spreadable map from this iterable.

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

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

    - #### public Collection 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(java.lang.Object) or Object#equals(java.lang.Object)). 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
      Since:
        2.4.0
      See Also:
        Iterable#toUnique(Comparator)

    - #### public Collection toUnique(Comparator 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

    - #### public List 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
      Since:
        2.4.0
      See Also:
        Iterable#indexed()

    - #### public List 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
      Since:
        2.4.0
      See Also:
        Iterable#indexed(int)