Package groovy.util

# Class GroovyCollections

java.lang.Object
groovy.util.GroovyCollections

public class GroovyCollections extends Object
Utility methods for working with combinations, subsequences, and aggregate collection operations.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GroovyCollections()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static List<List>`
  `combinations(Iterable<?> collections)`
  Finds all combinations of items from the given collections.
  `static List<List>`
  `combinations(Object[] collections)`
  Finds all combinations of items from the given collections.
  `static <T> List<List<T>>`
  `inits(Iterable<T> collections)`
  `static <T> T`
  `max(Iterable<T> items)`
  Selects the maximum value found in an Iterable.
  `static <T> T`
  `max(T[] items)`
  Selects the maximum value found in an array of items, so max([2, 4, 6] as Object[]) == 6.
  `static <T> T`
  `min(Iterable<T> items)`
  Selects the minimum value found in an Iterable of items.
  `static <T> T`
  `min(T[] items)`
  Selects the minimum value found in an array of items, so min([2, 4, 6] as Object[]) == 2.
  `static <T> Set<List<T>>`
  `subsequences(List<T> items)`
  Finds all non-empty subsequences of a list.
  `static Object`
  `sum(Iterable<?> items)`
  Sums all the given items.
  `static Object`
  `sum(Object[] items)`
  Sums all the items from an array of items.
  `static <T> List<List<T>>`
  `tails(Iterable<T> collections)`
  `static List`
  `transpose(Object[] lists)`
  Transposes an array of lists.
  `static List`
  `transpose(List lists)`
  Transposes the given lists.
  `static <T> List<T>`
  `union(Closure condition, Iterable<T>... iterables)`
  Returns an ordered set of all the unique items found in the provided argument iterables using the provided closure to compare items.
  `static <T> List<T>`
  `union(Iterable<T>... iterables)`
  Returns an ordered set of all the unique items found in the provided argument iterables.
  `static <T> List<T>`
  `union(Comparator<T> comparator, Iterable<T>... iterables)`
  Returns an ordered set of all the unique items found in the provided argument iterables using the provided comparator to compare items.
  `static <T> List<T>`
  `union(List<Iterable<T>> iterables)`
  Returns an ordered set of all the unique items found in the provided argument iterables.
  `static <T> List<T>`
  `union(List<Iterable<T>> iterables, Closure condition)`
  Returns an ordered set of all the unique items found in the provided argument iterables using the provided closure to compare items.
  `static <T> List<T>`
  `union(List<Iterable<T>> iterables, Comparator<T> comparator)`
  Returns an ordered set of all the unique items found in the provided argument iterables using the provided comparator to compare items.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### GroovyCollections

    public GroovyCollections()

- ## Method Details

  - ### combinations

    public static List<List> combinations(Object[] collections)
    Finds all combinations of items from the given collections.
    Parameters:
      `collections` - the given collections
    Returns:
      A list of the combinations found.
    See Also:
      - `combinations(Iterable)`

  - ### combinations

    public static List<List> combinations(Iterable<?> collections)
    Finds all combinations of items from the given collections. So, `combinations([[true, false], [true, false]])` is `[[true, true], [false, true], [true, false], [false, false]]` and `combinations([['a', 'b'],[1, 2, 3]])` is `[['a', 1], ['b', 1], ['a', 2], ['b', 2], ['a', 3], ['b', 3]]`. If a non-collection item is given, it is treated as a singleton collection, i.e. `combinations([[1, 2], 'x'])` is `[[1, 'x'], [2, 'x']]`. If an empty collection is found within the given collections, the result will be an empty list.
    Parameters:
      `collections` - the Iterable of given collections
    Returns:
      A list of the combinations found.
    Since:
      2.2.0

  - ### inits

    public static <T> List<List<T>> inits(Iterable<T> collections)
    Since:
      2.5.0

  - ### tails

    public static <T> List<List<T>> tails(Iterable<T> collections)
    Since:
      2.5.0

  - ### subsequences

    public static <T> Set<List<T>> subsequences(List<T> items)
    Finds all non-empty subsequences of a list. E.g. `subsequences([1, 2, 3])` would be: [[1, 2, 3], [1, 3], [2, 3], [1, 2], [1], [2], [3]]
    Parameters:
      `items` - the List of items
    Returns:
      the subsequences from items
    Since:
      1.8.0

  - ### transpose

    public static List transpose(Object[] lists)
    Transposes an array of lists.
    Parameters:
      `lists` - the given lists
    Returns:
      a List of the transposed lists
    See Also:
      - `transpose(List)`

  - ### transpose

    public static List transpose(List lists)
    Transposes the given lists. So, `transpose([['a', 'b'], [1, 2]])` is `[['a', 1], ['b', 2]]` and `transpose([['a', 'b', 'c']])` is `[['a'], ['b'], ['c']]`.
    Parameters:
      `lists` - the given lists
    Returns:
      a List of the transposed lists

  - ### min

    public static <T> T min(T[] items)
    Selects the minimum value found in an array of items, so min([2, 4, 6] as Object[]) == 2.
    Parameters:
      `items` - an array of items
    Returns:
      the minimum value

  - ### min

    public static <T> T min(Iterable<T> items)
    Selects the minimum value found in an Iterable of items.
    Parameters:
      `items` - an Iterable
    Returns:
      the minimum value
    Since:
      2.2.0

  - ### max

    public static <T> T max(T[] items)
    Selects the maximum value found in an array of items, so max([2, 4, 6] as Object[]) == 6.
    Parameters:
      `items` - an array of items
    Returns:
      the maximum value

  - ### max

    public static <T> T max(Iterable<T> items)
    Selects the maximum value found in an Iterable.
    Parameters:
      `items` - a Collection
    Returns:
      the maximum value
    Since:
      2.2.0

  - ### sum

    public static Object sum(Object[] items)
    Sums all the items from an array of items.
    Parameters:
      `items` - an array of items
    Returns:
      the sum of the items

  - ### sum

    public static Object sum(Iterable<?> items)
    Sums all the given items.
    Parameters:
      `items` - an Iterable of items
    Returns:
      the sum of the item
    Since:
      2.2.0

  - ### union

    public static <T> List<T> union(Iterable<T>... iterables)
    Returns an ordered set of all the unique items found in the provided argument iterables.

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

    Parameters:
      `iterables` - the sources of items
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0

  - ### union

    public static <T> List<T> union(List<Iterable<T>> iterables)
    Returns an ordered set of all the unique items found in the provided argument iterables.

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

    Parameters:
      `iterables` - the list of source items
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0

  - ### union

    public static <T> List<T> union(Comparator<T> comparator, Iterable<T>... iterables)
    Returns an ordered set of all the unique items found in the provided argument iterables using the provided comparator to compare items.

         assert GroovyCollections.union(n -> n.abs(), [1, 2, 5], [-3, -4, -5], [4, 6]) == [1, 2, 5, -3, -4, 6]
         assert GroovyCollections.union(n -> n.trunc(), [1.1, 2.2], [2.5, 3.3], [3.9, 4.1]) == [1.1, 2.2, 3.3, 4.1]
         assert GroovyCollections.union(w -> w.toUpperCase(), ['a', 'A'], ['B', 'a', 'c', 'b']) == ['a', 'B', 'c']

    Parameters:
      `comparator` - a Comparator
      `iterables` - the sources of items
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0

  - ### union

    public static <T> List<T> union(List<Iterable<T>> iterables, Comparator<T> comparator)
    Returns an ordered set of all the unique items found in the provided argument iterables using the provided comparator to compare items.

         assert GroovyCollections.union([[1, 2, 5], [-3, -4, -5], [4, 6]], n -> n.abs()) == [1, 2, 5, -3, -4, 6]
         assert GroovyCollections.union([[1.1, 2.2], [2.5, 3.3], [3.9, 4.1]], n -> n.trunc()) == [1.1, 2.2, 3.3, 4.1]
         assert GroovyCollections.union([['a', 'A'], ['B', 'a', 'c', 'b']], w -> w.toUpperCase()) == ['a', 'B', 'c']

    Parameters:
      `iterables` - the list of source items
      `comparator` - a Comparator
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0

  - ### union

    public static <T> List<T> union(@ClosureParams(value=FromString.class,options={"T","T,T"}) Closure condition, Iterable<T>... iterables)
    Returns an ordered set of all the unique items found in the provided argument iterables using the provided closure to compare items.

         def abs = { n -> n.abs() }
         assert GroovyCollections.union(abs, [1, 2, 5], [-3, -4, -5], [4, 6]) == [1, 2, 5, -3, -4, 6]

    Parameters:
      `condition` - a Closure used to determine unique items
      `iterables` - the sources of items
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0

  - ### union

    public static <T> List<T> union(List<Iterable<T>> iterables, @ClosureParams(value=FromString.class,options={"T","T,T"}) Closure condition)
    Returns an ordered set of all the unique items found in the provided argument iterables using the provided closure to compare items.

         assert GroovyCollections.union([[1, 2, 5], [-3, -4, -5], [4, 6]]){ n -> n.abs() } == [1, 2, 5, -3, -4, 6]

    Parameters:
      `iterables` - the list of source items
      `condition` - a Closure used to determine unique items
    Returns:
      the ordered list of unique values found
    Since:
      4.0.0