Set (Groovy JDK enhancements)

Package: java.util

## Interface Set

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `Set` | `asImmutable()` A convenience method for creating an immutable Set.
    `Set` | `asSynchronized()` A convenience method for creating a synchronized Set.
    `Set` | `asUnmodifiable()` Creates an unmodifiable view of a Set.
    `Set` | `each(Closure closure)` Iterates through a Set, passing each item to the given closure.
    `Set` | `eachWithIndex(Closure closure)` Iterates through a Set, passing each item and the item's index (a counter starting at zero) to the given closure.
    `boolean` | `equals(Set other)` Compare the contents of two Sets for equality using Groovy's coercion rules.
    `Set` | `findAll()` Finds the items matching the IDENTITY Closure (i.e. matching Groovy truth).
    `Set` | `findAll(Closure closure)` Finds all values matching the closure condition.
    `Set` | `flatten()` Flatten a Set.
    `Set` | `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.
    `Set` | `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.
    `Set` | `intersect(Iterable right)` Create a Set composed of the intersection of a Set and an Iterable.
    `Set` | `intersect(Iterable right, Comparator comparator)` Create a Set composed of the intersection of a Set and an Iterable.
    `Set` | `leftShift(Object value)` Overloads the left shift operator to provide an easy way to append objects to a Set.
    `Set` | `minus(Iterable removeMe)` Create a Set composed of the elements of the first Set minus the elements from the given Iterable.
    `Set` | `minus(Object removeMe)` Create a Set composed of the elements of the first Set minus the given element.
    `Set` | `minus(Collection removeMe)` Create a Set composed of the elements of the first Set minus the elements of the given Collection.
    `Set` | `plus(Iterable right)` Create a Set as a union of a Set and an Iterable.
    `Set` | `plus(Object right)` Create a Set as a union of a Set and an Object.
    `Set` | `plus(Collection right)` Create a Set as a union of a Set and a Collection.
    `List` | `split(Closure closure)` Splits all items into two collections based on the closure condition.

  - #### Methods inherited from interface java.util.Collection

    `addAll`, `addAll`, `addAll`, `asBoolean`, `asImmutable`, `asSynchronized`, `asType`, `asUnmodifiable`, `collectNested`, `each`, `eachWithIndex`, `find`, `find`, `findAll`, `findAll`, `flatten`, `getAt`, `getIndices`, `grep`, `grep`, `inject`, `inject`, `intersect`, `intersect`, `isCase`, `leftShift`, `minus`, `plus`, `plus`, `plus`, `removeAll`, `removeAll`, `removeElement`, `retainAll`, `retainAll`, `split`, `toListString`, `toListString`, `toSet`, `unique`, `unique`, `unique`, `unique`, `unique`, `unique`

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

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

- - ### Methods Detail

    - #### public Set asImmutable()

      A convenience method for creating an immutable Set.

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

    - #### public Set asSynchronized()

      A convenience method for creating a synchronized Set.

      Returns:
        a synchronized Set
      Since:
        1.0
      See Also:
        Collections#synchronizedSet(java.util.Set)

    - #### public Set asUnmodifiable()

      Creates an unmodifiable view of a Set.

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

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

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

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

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

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

    - #### public boolean equals(Set other)

      Compare the contents of two Sets for equality using Groovy's coercion rules.

      Returns `true` if the two sets have the same size, and every member of the specified set is contained in this set (or equivalently, every member of this set is contained in the specified set). If numbers exist in the sets, then they are compared as numbers, for example 2 == 2L. If both sets are `null`, the result is true; otherwise if either set is `null`, the result is `false`. Example usage:

          Set s1 = ["a", 2]
          def s2 = [2, 'a'] as Set
          Set s3 = [3, 'a']
          def s4 = [2.0, 'a'] as Set
          def s5 = [2L, 'a'] as Set
          assert s1.equals(s2)
          assert !s1.equals(s3)
          assert s1.equals(s4)
          assert s1.equals(s5)

      Parameters:
        `other` - the Set being compared to
      Returns:
        `true` if the contents of both sets are identical
      Since:
        1.8.0

    - #### public Set 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] as Set
          assert items.findAll() == [1, 2, true, 'foo', [4, 5]] as Set

      Returns:
        a Set of the values found
      Since:
        2.4.0
      See Also:
        Closure#IDENTITY

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

      Finds all values matching the closure condition.

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

      Parameters:
        `closure` - a closure condition
      Returns:
        a Set of matching values
      Since:
        2.4.0

    - #### public Set flatten()

      Flatten a Set. This Set and any nested arrays or collections have their contents (recursively) added to the new Set.

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

      Returns:
        a flattened Set
      Since:
        2.4.0

    - #### public Set 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] as Set
          assert items.grep() == [1, 2, true, 'foo', [4, 5]] as Set

      Returns:
        a Set of elements satisfy Groovy truth
      Since:
        2.4.0
      See Also:
        Closure#IDENTITY

    - #### public Set 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. This method can be used with different kinds of filters like regular expressions, classes, ranges etc. Example:

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

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

    - #### public Set intersect(Iterable right)

      Create a Set composed of the intersection of a Set and an Iterable. Any elements that exist in both iterables are added to the resultant collection.

          assert [4,5] as Set == ([1,2,3,4,5] as Set).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 Set as an intersection of a Set and an Iterable
      Since:
        2.4.0
      See Also:
        Set#intersect(Iterable, Comparator)

    - #### public Set intersect(Iterable right, Comparator comparator)

      Create a Set composed of the intersection of a Set and an Iterable. Any elements that exist in both iterables are added to the resultant collection.

      Parameters:
        `right` - an Iterable
        `comparator` - a Comparator
      Returns:
        a Set as an intersection of a Set and an Iterable
      Since:
        2.5.0

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

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

          def set = [1,2] as Set
          set << 3
          assert set == [1,2,3] as Set

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

    - #### public Set minus(Iterable removeMe)

      Create a Set composed of the elements of the first Set minus the elements from the given Iterable.

      Parameters:
        `removeMe` - the items to remove from the Set
      Returns:
        the resulting Set
      Since:
        1.8.7

    - #### public Set minus(Object removeMe)

      Create a Set composed of the elements of the first Set minus the given element.

      Parameters:
        `removeMe` - the element to remove from the Set
      Returns:
        the resulting Set
      Since:
        1.5.0

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

      Create a Set composed of the elements of the first Set minus the elements of the given Collection.

      Parameters:
        `removeMe` - the items to remove from the Set
      Returns:
        the resulting Set
      Since:
        1.5.0

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

      Create a Set as a union of a Set and an Iterable. This operation will always create a new object for the result, while the operands remain unchanged.

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

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

      Create a Set as a union of a Set and an Object. 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 Set
      Since:
        2.4.0

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

      Create a Set as a union of a Set and a Collection. This operation will always create a new object for the result, while the operands remain unchanged.

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

    - #### public List 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] as Set, [1,3] as Set] == ([1,2,3,4] as Set).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:
        2.4.0