Collection (Groovy JDK enhancements)

Package: java.util

## Interface Collection

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `boolean` | `addAll(Iterable items)` Adds all items from the iterable to the Collection.
    `boolean` | `addAll(Object[] items)` Modifies the collection by adding all the elements in the specified array to the collection.
    `boolean` | `addAll(Iterator items)` Adds all items from the iterator to the Collection.
    `boolean` | `asBoolean()` Coerce a collection instance to a boolean value.
    `Collection` | `asChecked(Class type)` Creates a checked view of a Collection.
    `Collection` | `asImmutable()` A convenience method for creating an immutable Collection.
    `Collection` | `asSynchronized()` Creates a synchronized view of a Collection.
    `Object` | `asType(Class clazz)` Converts the given collection to another type.
    `Collection` | `asUnmodifiable()` Creates an unmodifiable view of a Collection.
    `List` | `collectNested(Closure transform)` Recursively iterates through this collection transforming each non-Collection value into a new value using the closure as a transformer.
    `Collection` | `each(Closure closure)` Iterates through a Collection, passing each item to the given closure.
    `Collection` | `eachWithIndex(Closure closure)` Iterates through a Collection, passing each item and the item's index (a counter starting at zero) to the given closure.
    `Object` | `find()` Finds the first item matching the IDENTITY Closure (i.e. matching Groovy truth).
    `Object` | `find(Closure closure)` Finds the first value matching the closure condition.
    `Collection` | `findAll()` Finds the items matching the IDENTITY Closure (i.e. matching Groovy truth).
    `Collection` | `findAll(Closure closure)` Finds all values matching the closure condition.
    `Collection` | `flatten()` Flatten a Collection.
    `List` | `getAt(String property)` Support the subscript operator for Collection.
    `IntRange` | `getIndices()` Returns indices of the collection.
    `Collection` | `grep()` Iterates over the collection returning each element that matches using the IDENTITY Closure as a filter - effectively returning all elements which satisfy Groovy truth.
    `Collection` | `grep(Object filter)` Iterates over the collection of items and returns each item that matches the given filter - calling the `Object#isCase(java.lang.Object)` method used by switch statements. method can be used with different kinds of filters like regular expressions, classes, ranges etc.
    `Collection` | `intersect(Collection right)` Create a Collection composed of the intersection of both collections.
    `Collection` | `intersect(Collection right, Comparator comparator)` Create a Collection composed of the intersection of both collections.
    `boolean` | `isCase(Object switchValue)` Special 'case' implementation for collections which tests if the 'switch' operand is contained in any of the 'case' values.
    `boolean` | `isNotCase(Object switchValue)`
    `Collection` | `leftShift(Object value)` Overloads the left shift operator to provide an easy way to append objects to a Collection.
    `Collection` | `minus(Collection removeMe)` Create a new Collection composed of the elements of the first Collection minus every occurrence of elements of the given Collection.
    `Collection` | `plus(Iterable right)` Create a Collection as a union of a Collection and an Iterable.
    `Collection` | `plus(Object right)` Create a collection as a union of a Collection and an Object.
    `Collection` | `plus(Collection right)` Create a Collection as a union of two collections.
    `boolean` | `removeAll(Closure condition)` Modifies this collection by removing the elements that are matched according to the specified closure condition.
    `boolean` | `removeAll(Object[] items)` Modifies this collection by removing its elements that are contained within the specified object array.
    `boolean` | `removeElement(Object o)` Modifies this collection by removing a single instance of the specified element from this collection, if it is present.
    `boolean` | `retainAll(Closure condition)` Modifies this collection so that it retains only its elements that are matched according to the specified closure condition.
    `boolean` | `retainAll(Object[] items)` Modifies this collection so that it retains only its elements that are contained in the specified array.
    `Collection` | `split(Closure closure)` Splits all items into two collections based on the closure condition.
    `String` | `toListString()` Returns the string representation of the given list.
    `String` | `toListString(int maxSize)` Returns the string representation of the given list.
    `Set` | `toSet()` Convert a Collection to a Set.
    `Collection` | `union(Collection right)` Create a Collection composed of the union of both collections.
    `Collection` | `union(Collection right, Comparator comparator)` Create a Collection composed of the union of both collections.
    `Collection` | `unique()` Modifies this collection to remove all duplicated items, using Groovy's default number-aware comparator.
    `Collection` | `unique(boolean mutate)` Remove all duplicates from a given Collection using Groovy's default number-aware comparator.
    `Collection` | `unique(boolean mutate, Closure closure)` A convenience method for making a collection unique using a Closure to determine duplicate (equal) items.
    `Collection` | `unique(boolean mutate, Comparator comparator)` Remove all duplicates from a given Collection.
    `Collection` | `unique(Closure closure)` A convenience method for making a collection unique using a Closure to determine duplicate (equal) items.
    `Collection` | `unique(Comparator comparator)` Remove all duplicates from a given Collection.

  - #### Methods inherited from interface java.lang.Iterable

    `any`, `asCollection`, `asList`, `asType`, `average`, `average`, `bufferedIterator`, `chop`, `chop`, `collate`, `collate`, `collate`, `collate`, `collect`, `collect`, `collect`, `collectEntries`, `collectEntries`, `collectEntries`, `collectEntries`, `collectEntries`, `collectEntries`, `collectMany`, `collectMany`, `collectMany`, `collectNested`, `collectNested`, `combinations`, `combinations`, `contains`, `containsAll`, `count`, `count`, `count`, `countBy`, `countBy`, `disjoint`, `drop`, `dropRight`, `dropWhile`, `each`, `eachCombination`, `eachPermutation`, `eachWithIndex`, `every`, `findIndexOf`, `findIndexOf`, `findIndexValues`, `findIndexValues`, `findLastIndexOf`, `findLastIndexOf`, `findResult`, `findResult`, `findResult`, `findResult`, `findResults`, `findResults`, `first`, `flatten`, `flatten`, `flatten`, `flatten`, `flattenMany`, `getAt`, `groupBy`, `groupBy`, `groupBy`, `head`, `indexed`, `indexed`, `init`, `inits`, `inject`, `inject`, `injectAll`, `injectAll`, `interleave`, `interleave`, `intersect`, `intersect`, `intersect`, `isCase`, `isEmpty`, `join`, `join`, `last`, `max`, `max`, `max`, `min`, `min`, `min`, `minus`, `minus`, `minus`, `minus`, `multiply`, `permutations`, `permutations`, `plus`, `plus`, `repeat`, `repeat`, `size`, `sort`, `sort`, `sort`, `sort`, `sort`, `stream`, `sum`, `sum`, `sum`, `sum`, `tail`, `tails`, `take`, `takeRight`, `takeWhile`, `toList`, `toSet`, `toSorted`, `toSorted`, `toSorted`, `toSpreadMap`, `toUnique`, `toUnique`, `toUnique`, `union`, `union`, `union`, `withCollectedKeys`, `withCollectedKeys`, `withCollectedValues`, `withCollectedValues`, `withIndex`, `withIndex`, `zip`, `zipAll`

- - ### Methods Detail

    - #### public boolean addAll(Iterable items)

      Adds all items from the iterable to the Collection.

      Parameters:
        `items` - the items to add
      Returns:
        true if the collection changed

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

      Modifies the collection by adding all the elements in the specified array to the collection. The behavior of this operation is undefined if the specified array is modified while the operation is in progress.

      See also `plus` or the '+' operator if wanting to produce a new collection containing additional items but while leaving the original collection unchanged.

      Parameters:
        `items` - array containing elements to be added to this collection
      Returns:
        `true` if this collection changed as a result of the call
      Since:
        1.7.2
      See Also:
        Collections#addAll

    - #### public boolean addAll(Iterator items)

      Adds all items from the iterator to the Collection.

      Parameters:
        `items` - the items to add
      Returns:
        true if the collection changed

    - #### public boolean asBoolean()

      Coerce a collection instance to a boolean value. A collection is coerced to false if it's empty, and to true otherwise.

          assert [1,2].asBoolean() == true

          assert [].asBoolean() == false

      Returns:
        the boolean value
      Since:
        1.7.0

    - #### public Collection asChecked(Class type)

      Creates a checked view of a Collection.

      Parameters:
      Since:
        5.0.0
      See Also:
        Collections#checkedCollection

    - #### public Collection asImmutable()

      A convenience method for creating an immutable Collection.

      Returns:
        an unmodifiable view of a copy of the original, i.e. an effectively immutable copy
      Since:
        1.5.0
      See Also:
        List#asImmutable()
        Collection#asUnmodifiable()

    - #### public Collection asSynchronized()

      Creates a synchronized view of a Collection.

      Returns:
        a synchronized Collection
      Since:
        1.0
      See Also:
        Collections#synchronizedCollection(java.util.Collection)

    - #### public Object asType(Class clazz)

      Converts the given collection to another type. A default concrete type is used for List, Set, or SortedSet. If the given type has a constructor taking a collection, that is used. Otherwise, the call is deferred to Object#asType(Class). If this collection is already of the given type, the same instance is returned.

      Parameters:
        `clazz` - the desired class
      Returns:
        the object resulting from this type conversion
      Since:
        1.0
      See Also:
        Object#asType(java.lang.Class)

    - #### public Collection asUnmodifiable()

      Creates an unmodifiable view of a Collection.

      Returns:
        an unmodifiable view of the Collection
      Since:
        2.5.0
      See Also:
        Collections#unmodifiableCollection(java.util.Collection)
        List#asUnmodifiable()

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

      Recursively iterates through this collection 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 collection
      Returns:
        the resultant collection
      Since:
        1.8.1

    - #### public Collection each(Closure closure)

      Iterates through a Collection, passing each item to the given closure.

      Parameters:
        `closure` - the closure applied on each element found
      Returns:
        the self Collection
      Since:
        2.4.0

    - #### public Collection eachWithIndex(Closure closure)

      Iterates through a Collection, 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 Collection
      Since:
        2.4.0

    - #### public Object find()

      Finds the first item matching the IDENTITY Closure (i.e. matching Groovy truth).

      Example:

          def items = [null, 0, 0.0, false, '', [], 42, 43]
          assert items.find() == 42

      Returns:
        the first Object found or null if none was found
      Since:
        1.8.1
      See Also:
        Closure#IDENTITY

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

      Finds the first value matching the closure condition. Example:

          def list = [1,2,3]
          assert 2 == list.find { it > 1 }

      Parameters:
        `closure` - a closure condition
      Returns:
        the first Object found, in the order of the collections iterator, or null if no element matches
      Since:
        1.0

    - #### public Collection findAll()

      Finds the items matching the IDENTITY Closure (i.e. matching Groovy truth).

      Example:

          def items = [1, 2, 0, false, true, '', 'foo', [], [4, 5], null]
          assert items.findAll() == [1, 2, true, 'foo', [4, 5]]

      Returns:
        a Collection of the truthy values
      Since:
        1.8.1
      See Also:
        Closure#IDENTITY

    - #### public Collection findAll(Closure closure)

      Finds all values matching the closure condition.

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

      Parameters:
        `closure` - a closure condition
      Returns:
        a Collection of matching values
      Since:
        1.5.6

    - #### public Collection flatten()

      Flatten a Collection. This Collection 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 List getAt(String property)

      Support the subscript operator for Collection.

          assert [String, Long, Integer] == ["a",5L,2]["class"]

      Parameters:
        `property` - a String
      Returns:
        a List
      Since:
        1.0

    - #### public IntRange getIndices()

      Returns indices of the collection.

      Example:

          assert 0..2 == [5, 6, 7].indices

      Returns:
        an index range
      Since:
        2.4.0

    - #### public Collection grep()

      Iterates over the collection returning each element that matches using the IDENTITY Closure as a filter - effectively returning all elements which satisfy Groovy truth.

      Example:

          def items = [1, 2, 0, false, true, '', 'foo', [], [4, 5], null]
          assert items.grep() == [1, 2, true, 'foo', [4, 5]]

      Returns:
        a collection of elements satisfy Groovy truth
      Since:
        2.0
      See Also:
        Closure#IDENTITY

    - #### public Collection grep(Object filter)

      Iterates over the collection of items and returns each item that matches the given filter - calling the `Object#isCase(java.lang.Object)` method used by switch statements. method can be used with different kinds of filters like regular expressions, classes, ranges etc. Example:

          def list = ['a', 'b', 'aa', 'bc', 3, 4.5]
          assert list.grep( ~/a+/ )  == ['a', 'aa']
          assert list.grep( ~/../ )  == ['aa', 'bc']
          assert list.grep( Number ) == [ 3, 4.5 ]
          assert list.grep{ it.toString().size() == 1 } == [ 'a', 'b', 3 ]

      Parameters:
        `filter` - the filter to perform on each element of the collection (using the Object#isCase(java.lang.Object) method)
      Returns:
        a collection of objects which match the filter
      Since:
        2.0

    - #### public Collection intersect(Collection right)

      Create a Collection composed of the intersection of both collections. Any elements that exist in both collections are added to the resultant collection. For collections 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` - a Collection
      Returns:
        a Collection as an intersection of both collections
      Since:
        1.5.6
      See Also:
        Collection#intersect(Collection, Comparator)

    - #### public Collection intersect(Collection right, Comparator comparator)

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

          assert [3,4] == [1,2,3,4].intersect([3,4,5,6], Comparator.naturalOrder())
          assert [2,4] == [1,2,3,4].intersect([4,8,12,16,20], (x, y) -> x * x <=> y)

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

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

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

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

          switch( 3 ) {
            case [1,3,5]:
              assert true
              break
            default:
              assert false
          }

      Parameters:
        `switchValue` - the switch value
      Returns:
        true if the caseValue is deemed to contain the switchValue
      Since:
        1.0
      See Also:
        Collection#contains(java.lang.Object)

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

      Parameters:
      Since:
        4.0.0

    - #### public Collection leftShift(Object value)

      Overloads the left shift operator to provide an easy way to append objects to a Collection.

          def list = [1,2]
          list << 3
          assert list == [1,2,3]

      Parameters:
        `value` - an Object to be added to the collection.
      Returns:
        same collection, after the value was added to it.
      Since:
        1.0

    - #### public Collection minus(Collection removeMe)

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

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

      Parameters:
        `removeMe` - a Collection of elements to remove
      Returns:
        a Collection with the given elements removed
      Since:
        2.4.0

    - #### public Collection plus(Iterable right)

      Create a Collection as a union of a Collection and an Iterable. If the left collection 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.

      Parameters:
        `right` - the right Iterable
      Returns:
        the merged Collection
      Since:
        1.8.7
      See Also:
        Collection#plus(Collection)

    - #### public Collection plus(Object right)

      Create a collection as a union of a Collection and an Object. If the collection 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:
        1.5.0

    - #### public Collection plus(Collection right)

      Create a Collection as a union of two collections. If the left collection 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 Collection
      Returns:
        the merged Collection
      Since:
        1.5.0

    - #### public boolean removeAll(Closure condition)

      Modifies this collection by removing the elements that are matched according to the specified closure condition.

          def list = ['a', 'b']
          list.removeAll { it == 'b' }
          assert list == ['a']

      See also `findAll` and `grep` when wanting to produce a new list containing items which match some criteria but leaving the original collection unchanged.
      Parameters:
        `condition` - a closure condition
      Returns:
        `true` if this collection changed as a result of the call
      Since:
        1.7.2
      See Also:
        Iterator#remove()

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

      Modifies this collection by removing its elements that are contained within the specified object array. See also `findAll` and `grep` when wanting to produce a new list containing items which don't match some criteria while leaving the original collection unchanged.

      Parameters:
        `items` - array containing elements to be removed from this collection
      Returns:
        `true` if this collection changed as a result of the call
      Since:
        1.7.2
      See Also:
        Collection#removeAll(Collection)

    - #### public boolean removeElement(Object o)

      Modifies this collection by removing a single instance of the specified element from this collection, if it is present. Essentially an alias for Collection#remove(Object) but with no ambiguity for Collection<Integer>.

      Example:

          def list = [1, 2, 3, 2]
          list.removeElement(2)
          assert [1, 3, 2] == list

      Parameters:
        `o` - element to be removed from this collection, if present
      Returns:
        true if an element was removed as a result of this call
      Since:
        2.4.0

    - #### public boolean retainAll(Closure condition)

      Modifies this collection so that it retains only its elements that are matched according to the specified closure condition. In other words, removes from this collection all of its elements that don't match.

          def list = ['a', 'b']
          list.retainAll { it == 'b' }
          assert list == ['b']

      See also `findAll` and `grep` when wanting to produce a new list containing items which match some criteria but leaving the original collection unchanged.
      Parameters:
        `condition` - a closure condition
      Returns:
        `true` if this collection changed as a result of the call
      Since:
        1.7.2
      See Also:
        Iterator#remove()

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

      Modifies this collection so that it retains only its elements that are contained in the specified array. In other words, removes from this collection all of its elements that are not contained in the specified array. See also `grep` and `findAll` when wanting to produce a new list containing items which match some specified items but leaving the original collection unchanged.

      Parameters:
        `items` - array containing elements to be retained from this collection
      Returns:
        `true` if this collection changed as a result of the call
      Since:
        1.7.2
      See Also:
        Collection#retainAll(Collection)

    - #### public Collection split(Closure closure)

      Splits all items into two collections based on the closure condition. The first list contains all items which match the closure expression. The second list all those that don't.

      Example usage:

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

      Parameters:
        `closure` - a closure condition
      Returns:
        a List whose first item is the accepted values and whose second item is the rejected values
      Since:
        1.6.0

    - #### public String toListString()

      Returns the string representation of the given list. The string displays the contents of the list, similar to a list literal, i.e. `[1, 2, a]`.

      Returns:
        the string representation
      Since:
        1.0

    - #### public String toListString(int maxSize)

      Returns the string representation of the given list. The string displays the contents of the list, similar to a list literal, i.e. `[1, 2, a]`.

      Parameters:
        `maxSize` - stop after approximately this many characters and append '...'
      Returns:
        the string representation
      Since:
        1.7.3

    - #### public Set toSet()

      Convert a Collection to a Set. Always returns a new Set even if the Collection 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:
        1.8.0

    - #### public Collection union(Collection right)

      Create a Collection composed of the union of both collections. Any elements that exist in either collections are added to the resultant collection, such that no elements are duplicated in the resultant collection. For collections 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 exists in the resultant collection.
      Parameters:
        `right` - a Collection
      Returns:
        a Collection as a union of both collections
      Since:
        5.0.0
      See Also:
        Collection#union(Collection, Comparator)

    - #### public Collection union(Collection right, Comparator comparator)

      Create a Collection composed of the union of both collections. Any elements that exist in either collections are added to the resultant collection, such that no elements are duplicated in the resultant collection. For collections 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())
          assert [4,8,12,16,20,1,3] == [4,8,12,16,20].union([1,2,3,4], (x, y) -> x * x <=> y)

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

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

    - #### public Collection unique()

      Modifies this collection to remove all duplicated items, using Groovy's default number-aware comparator.

          assert [1,3] == [1,3,3].unique()

      Returns:
        the now modified collection
      Since:
        1.0
      See Also:
        Collection#unique(boolean)

    - #### public Collection unique(boolean mutate)

      Remove all duplicates from a given Collection using Groovy's default number-aware comparator. If mutate is true, it works by modifying the original object (and also returning it). If mutate is false, a new collection is returned leaving the original unchanged.

          assert [1,3] == [1,3,3].unique()

          def orig = [1, 3, 2, 3]
          def uniq = orig.unique(false)
          assert orig == [1, 3, 2, 3]
          assert uniq == [1, 3, 2]

      Parameters:
        `mutate` - false will return a new collection containing the unique items from the collection, true will mutate collections in place and return the original collection
      Returns:
        a collection with unique elements
      Since:
        1.8.1

    - #### public Collection unique(boolean mutate, Closure closure)

      A convenience method for making a collection unique using a Closure to determine duplicate (equal) items. If mutate is true, it works on the receiver object and returns it. If mutate is false, a new collection is returned.

      If the closure takes a single parameter, each element from the Collection 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 collection will be passed as arguments, and the closure should return an int value (with 0 indicating the items are not unique).

          def orig = [1, 3, 4, 5]
          def uniq = orig.unique(false) { it % 2 }
          assert orig == [1, 3, 4, 5]
          assert uniq == [1, 4]

          def orig = [2, 3, 3, 4]
          def uniq = orig.unique(false) { a, b -> a <=> b }
          assert orig == [2, 3, 3, 4]
          assert uniq == [2, 3, 4]

      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 unique items
      Returns:
        self without any duplicates
      Since:
        1.8.1

    - #### public Collection unique(boolean mutate, Comparator comparator)

      Remove all duplicates from a given Collection. If mutate is true, it works on the original object (and also returns it). If mutate is false, a new collection is returned. The order of members in the Collection are compared by the given Comparator. For each duplicate, the first member which is returned by the given Collection's iterator is retained, but all other ones are removed. The given Collection's original order is preserved.

          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.unique(false, new PersonComparator())
          assert( list2 != list && list2 == [a, b, c] )

      Parameters:
        `mutate` - false will always cause a new collection to be created, true will mutate collections in place
        `comparator` - a Comparator
      Returns:
        self the collection without duplicates
      Since:
        1.8.1

    - #### public Collection unique(Closure closure)

      A convenience method for making a collection unique using a Closure to determine duplicate (equal) items.

      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 collection will be passed as arguments, and the closure should return an int value (with 0 indicating the items are not unique).

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

          assert [2,3,4] == [2,3,3,4].unique { a, b -> a <=> b }

      Parameters:
        `closure` - a 1 or 2 arg Closure used to determine unique items
      Returns:
        self without any duplicates
      Since:
        1.0
      See Also:
        Collection#unique(boolean, Closure)

    - #### public Collection unique(Comparator comparator)

      Remove all duplicates from a given Collection. Works on the original object (and also returns it). The order of members in the Collection are compared by the given Comparator. For each duplicate, the first member which is returned by the given Collection's iterator is retained, but all other ones are removed. The given Collection's original order is preserved.

          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.unique(new PersonComparator())
          assert( list2 == list && list == [a, b, c] )

      Parameters:
        `comparator` - a Comparator
      Returns:
        self the now modified collection without duplicates
      Since:
        1.0
      See Also:
        Collection#unique(boolean, java.util.Comparator)