Methods Detail

• 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

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

• 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 Object asType(Class clazz)

  Converts the given iterable to another type.

  Parameters:

  clazz - the desired class

  Returns:

  the object resulting from this type conversion

  Since:

  2.4.12

  See Also:

  Collection#asType(Class)

• 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

  Since:

  3.0.0

  See Also:

  Iterator#average()

• 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().

  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

• public BufferedIterator 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

• public List chop(int chopSizes)

  Chops the Iterable into pieces, returning lists with sizes corresponding to the supplied chop sizes. If the Iterable isn't large enough, truncated (possibly empty) pieces are returned. 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

  Since:

  2.5.2

  See Also:

  Iterable#collate(int)

• 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 List 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

  Since:

  2.5.0

  See Also:

  Closure#IDENTITY

• public List collect(Closure 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

• public Object collect(Object collector, Closure 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

• 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 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 Map collectEntries(Map collector, Function keyTransform, Function 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

• public Map collectEntries(Function keyTransform, Function 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

• 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:

  Iterable#sum(groovy.lang.Closure)

• public Object collectMany(Object 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']
  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().collect() }
    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

• 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 Object collectNested(Object 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()

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

  Since:

  2.2.0

  See Also:

  GroovyCollections#combinations(Iterable)

• public List combinations(Closure 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.

  Since:

  2.2.0

  See Also:

  GroovyCollections#combinations(Iterable)

  Iterable#collect(Closure)

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

  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 Object count(Object 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

• public Map 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 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 than 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 than 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 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

• 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

• 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

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

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

• 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

• 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

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

• public Object findResult(Closure 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

• public Object findResult(Object 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

• public Object findResult(Object defaultResult, Closure 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

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

• 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(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.

  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

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

• public Collection 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.

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

  Since:

  1.6.0

  See Also:

  Iterable#flattenMany(Closure)

  Iterable#collectNested(Closure)

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

  Since:

  5.0.0

  See Also:

  Iterable#collectMany(Closure)

• 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 List 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

• public Object inject(Closure 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'
  

  Parameters:

  closure - a closure

  Returns:

  the result of the last closure call

  Since:

  5.0.0

  See Also:

  Iterable#inject(Object, Closure)

• public Object inject(Object initialValue, Closure 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

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

  Since:

  2.4.0

  See Also:

  Iterable#intersect(Iterable, Comparator)

• public Collection intersect(Iterable 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(java.lang.Object) or Object#equals(java.lang.Object)). 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 Collection intersect(Iterable right, Comparator 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

• public boolean isCase(Object switchValue)

  'Case' implementation for iterable types 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

  Since:

  5.0.0

  See Also:

  Iterable#contains(Object)

• 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

• 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

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

  Returns:

  the last 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:

  Iterator#max()

• 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

  See Also:

  Iterator#max(Comparator)

• public Object min()

  Adds min() method to Collection objects.

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

  Returns:

  the minimum value

  Since:

  1.0

  See Also:

  Iterator#min()

• 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

  See Also:

  Iterator#min()

• 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

  See Also:

  Iterator#min(java.util.Comparator)

• 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(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 - an Iterable of elements to remove

  condition - a Closure used to determine unique items

  Returns:

  a new Collection with the given elements removed

  Since:

  4.0.0

• public Collection minus(Iterable removeMe, Comparator 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.

  assert ['a', 'B', 'c', 'D', 'E'].minus(['b', 'C', 'D'], (i, j) -> i.toLowerCase() <=> j.toLowerCase()) == ['a', 'E']
  

  Parameters:

  removeMe - an Iterable of elements to remove

  comparator - a Comparator

  Returns:

  a new Collection with the given elements removed

  Since:

  4.0.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:

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

  Iterable#sort(boolean, Closure)

• public Stream 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

  Since:

  2.2.0

  See Also:

  Iterator#sum()

• 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

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

  Since:

  2.2.0

  See Also:

  Iterator#sum(Object)

• 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

• 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 List 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

• 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 than 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 than 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 Collection union(Iterable 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

  Since:

  5.0.0

  See Also:

  Iterable#union(Iterable, Comparator)

• public Collection union(Iterable 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(java.lang.Object) or Object#equals(java.lang.Object)). 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

• public Collection union(Iterable right, Comparator 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

• public Map withCollectedKeys(Map collector, Function 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(Map, Function, Function) 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

• public Map withCollectedKeys(Function 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(Function, Function) 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

• public Map withCollectedValues(Map collector, Function 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(Map, Function, Function) 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

• public Map withCollectedValues(Function 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(Function, Function) 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

• 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)

• public Iterator zip(Iterable other)

  An iterator of all the pairs of two Iterables.

  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:

  an iterator of all the pairs from self and other

  Since:

  5.0.0