Package: java.util

## [Java] Interface Set

-     public interface Set

  GDK enhancements for Set.

  displayName:
    Set
  receiverFqcn:
    java.util.Set

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public Set<T>` | `and(Iterable<T> right)` Creates a Set composed of the intersection of a Set and an Iterable.
    `<T>` | `public Set<T>` | `and(Iterable<T> right, Comparator<? super T> comparator)` Creates a Set composed of the intersection of a Set and an Iterable.
    `<T>` | `public Set<T>` | `asChecked(Class<T> type)` Creates a checked view of a Set.
    `<T>` | `public Set<T>` | `asImmutable()` A convenience method for creating an immutable Set.
    `<T>` | `public Set<T>` | `asSynchronized()` Creates a synchronized view of a Set.
    `<T>` | `public Set<T>` | `asUnmodifiable()` Creates an unmodifiable view of a Set.
    `<T>` | `public Set<T>` | `each(Closure closure)` Iterates through a Set, passing each item to the given closure.
    `<T>` | `public Set<T>` | `eachWithIndex(Closure closure)` Iterates through a Set, passing each item and the item's index (a counter starting at zero) to the given closure.
    `<T>` | `public boolean` | `equals(Set<T> other)` Compare the contents of two Sets for equality using Groovy's coercion rules.
    `<T>` | `public Set<T>` | `findAll(Closure closure)` Finds all values matching the closure condition.
    `<T>` | `public Set<T>` | `findAll(Predicate<? super T> condition)` Finds all values matching the given predicate, preserving the Set type.
    `<T, P>` | `public Set<T>` | `findAll(BiPredicate<? super T, ? super P> condition, P param)` Finds all values matching the given two-argument condition, with the supplied `param` fixed as the second argument, preserving the Set type.
    `<T>` | `public Set<T>` | `findAll()` Finds the items matching the IDENTITY Closure (i.e. matching Groovy truth).
    `<T, E>` | `public Set<T>` | `flatten()` Flatten a Set.
    `<T>` | `public Set<T>` | `grep(Object filter)` Iterates over the collection of items and returns each item that matches the given filter - calling the `Object.isCase` method used by switch statements.
    `<T>` | `public Set<T>` | `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.
    `<T>` | `public Set<T>` | `intersect(Iterable<T> right)` Create a Set composed of the intersection of a Set and an Iterable.
    `<T>` | `public Set<T>` | `intersect(Iterable<T> right, Comparator<? super T> comparator)` Create a Set composed of the intersection of a Set and an Iterable.
    `<T>` | `public Set<T>` | `leftShift(T value)` Overloads the left shift operator to provide an easy way to append objects to a Set.
    `<T>` | `public Set<T>` | `minus(Collection<?> removeMe)` Create a Set composed of the elements of the first Set minus the elements of the given Collection.
    `<T>` | `public Set<T>` | `minus(Iterable<?> removeMe)` Create a Set composed of the elements of the first Set minus the elements from the given Iterable.
    `<T>` | `public Set<T>` | `minus(Object removeMe)` Create a Set composed of the elements of the first Set minus the given element.
    `<T>` | `public Set<T>` | `or(Iterable<T> right)` Create a Set as a union of a Set and an Iterable.
    `<T>` | `public Set<T>` | `plus(Iterable<T> right)` Create a Set as a union of a Set and an Iterable.
    `<T>` | `public Set<T>` | `plus(Collection<T> right)` Create a Set as a union of a Set and a Collection.
    `<T>` | `public Set<T>` | `plus(T right)` Create a Set as a union of a Set and an Object.
    `<T>` | `public List<Set<T>>` | `split(Closure closure)` Splits all items into two collections based on the closure condition.
    `<T>` | `public Set<T>` | `union(Iterable<T> right)` Create a Set composed of the union of a Set and an Iterable.
    `<T>` | `public Set<T>` | `union(Iterable<T> right, Comparator<? super T> comparator)` Create a Set composed of the union of a Set and an Iterable.
    `<T>` | `public Set<T>` | `xor(Iterable<T> right)` Create a Set composed of the symmetric difference of a Set and an Iterable.
    `<T>` | `public Set<T>` | `xor(Iterable<T> right, Comparator<? super T> comparator)` Create a Set composed of the symmetric difference of a Set and an Iterable.

- - ### Method Detail

    - #### <T> public Set<T> and(Iterable<T> right)

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

      This operation will always create a new object for the result, while the operands remain unchanged.

           def a = [1,2,3,4] as Set
           def b = [3,4,5,6] as Set
           assert (a & b) == [3,4] as Set

      By default, Groovy uses a NumberAwareComparator when determining if an element exists in both sets.
      Parameters:
        `right` - an Iterable
      Returns:
        a Set as an intersection of a Set and an Iterable
      See Also:
        intersect(Set, Iterable)
      Since:
        5.0.0

    - #### <T> public Set<T> and(Iterable<T> right, Comparator<? super T> comparator)

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

      This operation will always create a new object for the result, while the operands remain unchanged.

           assert [3,4] as Set == ([1,2,3,4] as Set).and([3,4,5,6], Comparator.naturalOrder())

      Parameters:
        `right` - an Iterable
        `comparator` - a Comparator
      Returns:
        a Set as an intersection of a Set and an Iterable
      See Also:
        intersect(Set, Iterable, Comparator)
      Since:
        5.0.0

    - #### <T> public Set<T> asChecked(Class<T> type)

      Creates a checked view of a Set.

      See Also:
        Collections.checkedSet
      Since:
        5.0.0

    - #### <T> public Set<T> 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
      See Also:
        asImmutable(java.util.List)
        asUnmodifiable(java.util.Set)
      Since:
        1.0

    - #### <T> public Set<T> asSynchronized()

      Creates a synchronized view of a Set.

      Returns:
        a synchronized Set
      See Also:
        Collections.synchronizedSet
      Since:
        1.0

    - #### <T> public Set<T> asUnmodifiable()

      Creates an unmodifiable view of a Set.

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

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

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

    - #### <T> public boolean equals(Set<T> 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

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

    - #### <T> public Set<T> findAll(Predicate<? super T> condition)

      Finds all values matching the given predicate, preserving the Set type. A "fat-free" variant of Set.findAll accepting a Predicate.

          assert ([2, 4] as Set) == ([1, 2, 3, 4] as Set).findAll(n -> n % 2 == 0)

      Parameters:
        `condition` - the predicate condition
      Returns:
        a Set of matching values
      Since:
        6.0.0

    - #### <T, P> public Set<T> findAll(BiPredicate<? super T, ? super P> condition, P param)

      Finds all values matching the given two-argument condition, with the supplied `param` fixed as the second argument, preserving the Set type. This is the Set-preserving counterpart of Iterable.findAll, combining Set.findAll with the right-currying performed by Lambdas.curryWith, so that `set.findAll(condition, param)` is equivalent to `set.findAll(curryWith(condition, param))`.

           import java.util.function.BiPredicate
           BiPredicate<Integer, Integer> divisibleBy = (n, d) -> n % d == 0
           assert ([1, 2, 3, 4, 5, 6] as Set).findAll(divisibleBy, 2) == ([2, 4, 6] as Set)

      Parameters:
        `condition` - a two-argument predicate condition
        `param` - the value to fix as the predicate's second argument
      Returns:
        a Set of matching values
      Since:
        6.0.0

    - #### <T> public Set<T> 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 truthy values
      Since:
        2.4.0
      See Also:
        Closure.IDENTITY

    - #### <T, E> public Set<T> 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

    - #### <T> public Set<T> grep(Object filter)

      Iterates over the collection of items and returns each item that matches the given filter - calling the `Object.isCase` 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 method)
      Returns:
        a Set of objects which match the filter
      Since:
        2.4.0

    - #### <T> public Set<T> 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
      See Also:
        Closure.IDENTITY
      Since:
        2.4.0

    - #### <T> public Set<T> intersect(Iterable<T> 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
      See Also:
        intersect(Set, Iterable, Comparator)
      Since:
        2.4.0

    - #### <T> public Set<T> intersect(Iterable<T> right, Comparator<? super T> 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.

           assert [3,4] as Set == ([1,2,3,4] as Set).intersect([3,4,5,6], Comparator.naturalOrder())

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

    - #### <T> public Set<T> leftShift(T 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

    - #### <T> public Set<T> minus(Collection<?> removeMe)

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

      Parameters:
        `removeMe` - the elements to exclude
      Returns:
        a new Set
      Since:
        1.5.0

    - #### <T> public Set<T> minus(Iterable<?> removeMe)

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

      Parameters:
        `removeMe` - the elements to exclude
      Returns:
        a new Set
      Since:
        1.8.7

    - #### <T> public Set<T> minus(Object removeMe)

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

      Parameters:
        `removeMe` - the element to exclude
      Returns:
        a new Set
      Since:
        1.5.0

    - #### <T> public Set<T> or(Iterable<T> right)

      Create a Set as a union of a Set and an Iterable. Any elements that exist in either are added to the resultant Set.

      This operation will always create a new object for the result, while the operands remain unchanged.

           def a = [1,2,3,4] as Set
           def b = [3,4,5,6] as Set
           assert (a | b) == [1,2,3,4,5,6] as Set

      Parameters:
        `right` - the right Iterable
      Returns:
        the merged Set
      Since:
        5.0.0
      See Also:
        plus(Set, Iterable)

    - #### <T> public Set<T> plus(Iterable<T> 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:
        plus(Collection, Collection)

    - #### <T> public Set<T> plus(Collection<T> 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:
        plus(Collection, Collection)

    - #### <T> public Set<T> plus(T 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

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

    - #### <T> public Set<T> union(Iterable<T> right)

      Create a Set composed of the union of a Set and an Iterable. Any elements that exist in either iterables are added to the resultant collection, such that no elements are duplicated in the resultant collection.

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

    - #### <T> public Set<T> union(Iterable<T> right, Comparator<? super T> comparator)

      Create a Set composed of the union of a Set and an Iterable. Any elements that exist in either iterables are added to the resultant collection, such that no elements are duplicated in the resultant collection.

           assert [1,2,3,4,5,6] as Set == ([1,2,3,4] as Set).union([3,4,5,6], Comparator.naturalOrder())

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

    - #### <T> public Set<T> xor(Iterable<T> right)

      Create a Set composed of the symmetric difference of a Set and an Iterable. Any elements that exit in only one are added to the resultant Set.

      This operation will always create a new object for the result, while the operands remain unchanged.

           def a = [1,2,3,4] as Set
           def b = [3,4,5,6] as Set
           assert (a ^ b) == [1,2,5,6] as Set

      By default, Groovy uses a NumberAwareComparator when determining if an element exists in both sets.
      Parameters:
        `right` - an Iterable
      Returns:
        a Set as a symmetric difference of a Set and an Iterable
      Since:
        5.0.0

    - #### <T> public Set<T> xor(Iterable<T> right, Comparator<? super T> comparator)

      Create a Set composed of the symmetric difference of a Set and an Iterable. Any elements that exit in only one are added to the resultant Set.

      This operation will always create a new object for the result, while the operands remain unchanged.

           assert [1,2,5,6] as Set == ([1,2,3,4] as Set).xor([3,4,5,6], Comparator.naturalOrder())

      Parameters:
        `right` - an Iterable
        `comparator` - a Comparator
      Returns:
        a Set as a symmetric difference of a Set and an Iterable
      Since:
        5.0.0