Package: java.util

## [Java] Interface SortedSet

-     public interface SortedSet

  GDK enhancements for SortedSet.

  displayName:
    SortedSet
  receiverFqcn:
    java.util.SortedSet

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public SortedSet<T>` | `and(Iterable<T> right)` Creates a SortedSet composed of the intersection of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `and(Iterable<T> right, Comparator<? super T> comparator)` Creates a SortedSet composed of the intersection of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `asChecked(Class<T> type)` Creates a checked view of a SortedSet.
    `<T>` | `public SortedSet<T>` | `asImmutable()` A convenience method for creating an immutable SortedSet.
    `<T>` | `public SortedSet<T>` | `asSynchronized()` Creates a synchronized view of a SortedSet.
    `<T>` | `public SortedSet<T>` | `asUnmodifiable()` Creates an unmodifiable view of a SortedSet.
    `<T>` | `public SortedSet<T>` | `drop(int num)` Drops the given number of elements from the head of this List.
    `<T>` | `public SortedSet<T>` | `dropRight(int num)` Drops the given number of elements from the tail of this SortedSet.
    `<T>` | `public SortedSet<T>` | `dropWhile(Closure condition)` Returns a suffix of this SortedSet where elements are dropped from the front while the given Closure evaluates to true.
    `<T>` | `public SortedSet<T>` | `each(Closure closure)` Iterates through a SortedSet, passing each item to the given closure.
    `<T>` | `public SortedSet<T>` | `eachWithIndex(Closure closure)` Iterates through a SortedSet, passing each item and the item's index (a counter starting at zero) to the given closure.
    `<T, E>` | `public SortedSet<T>` | `flatten()` Flatten a SortedSet.
    `<T>` | `public SortedSet<T>` | `init()` Returns the items from the SortedSet excluding the last item.
    `<T>` | `public SortedSet<T>` | `intersect(Iterable<T> right)` Create a SortedSet composed of the intersection of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `intersect(Iterable<T> right, Comparator<? super T> comparator)` Create a SortedSet composed of the intersection of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `leftShift(T value)` Overloads the left shift operator to provide an easy way to append objects to a SortedSet.
    `<T>` | `public SortedSet<T>` | `minus(Collection<?> removeMe)` Create a SortedSet composed of the elements of the first SortedSet minus the elements of the given Collection.
    `<T>` | `public SortedSet<T>` | `minus(Iterable<?> removeMe)` Create a SortedSet composed of the elements of the first SortedSet minus the elements of the given Iterable.
    `<T>` | `public SortedSet<T>` | `minus(Object removeMe)` Create a SortedSet composed of the elements of the first SortedSet minus the given element.
    `<T>` | `public SortedSet<T>` | `or(Iterable<T> right)` Create a SortedSet as a union of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `plus(Iterable<T> right)` Create a SortedSet as a union of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `plus(Collection<T> right)` Create a SortedSet as a union of a SortedSet and a Collection.
    `<T>` | `public SortedSet<T>` | `plus(T right)` Create a SortedSet as a union of a SortedSet and an Object.
    `<T>` | `public SortedSet<T>` | `sort()` Avoids doing unnecessary work when sorting an already sorted set (i.e. an identity function for an already sorted set).
    `<T>` | `public SortedSet<T>` | `tail()` Returns the items from the SortedSet excluding the first item.
    `<T>` | `public SortedSet<T>` | `take(int num)` Returns the first `num` elements from the head of this SortedSet.
    `<T>` | `public SortedSet<T>` | `takeRight(int num)` Returns the last `num` elements from the tail of this SortedSet.
    `<T>` | `public SortedSet<T>` | `takeWhile(Closure condition)` Returns the longest prefix of this SortedSet where each element passed to the given closure condition evaluates to true.
    `<T>` | `public Set<T>` | `toSorted()` Avoids doing unnecessary work when sorting an already sorted set
    `<T>` | `public SortedSet<T>` | `union(Iterable<T> right)` Create a SortedSet composed of the union of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `union(Iterable<T> right, Comparator<? super T> comparator)` Create a SortedSet composed of the intersection of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `xor(Iterable<T> right)` Create a SortedSet composed of the symmetric difference of a SortedSet and an Iterable.
    `<T>` | `public SortedSet<T>` | `xor(Iterable<T> right, Comparator<? super T> comparator)` Create a SortedSet composed of the symmetric difference of a SortedSet and an Iterable.

- - ### Method Detail

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

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

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

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

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

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

      Creates a SortedSet composed of the intersection of a SortedSet 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 SortedSet == ([1,2,3,4] as SortedSet).and([3,4,5,6], Comparator.naturalOrder())

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

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

      Creates a checked view of a SortedSet.

      See Also:
        Collections.checkedSortedSet
      Since:
        5.0.0

    - #### <T> public SortedSet<T> asImmutable()

      A convenience method for creating an immutable SortedSet.

      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.SortedSet)
      Since:
        1.0

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

      Creates a synchronized view of a SortedSet.

      Returns:
        a synchronized SortedSet
      See Also:
        Collections.synchronizedSortedSet
      Since:
        1.0

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

      Creates an unmodifiable view of a SortedSet.

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

    - #### <T> public SortedSet<T> drop(int num)

      Drops the given number of elements from the head of this List.

           def strings = [ 'a', 'b', 'c' ] as SortedSet
           assert strings.drop( 0 ) == [ 'a', 'b', 'c' ] as SortedSet
           assert strings.drop( 2 ) == [ 'c' ] as SortedSet
           assert strings.drop( 5 ) == [] as SortedSet

      Parameters:
        `num` - the number of elements to drop from this Iterable
      Returns:
        a SortedSet 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:
        2.4.0

    - #### <T> public SortedSet<T> dropRight(int num)

      Drops the given number of elements from the tail of this SortedSet.

           def strings = [ 'a', 'b', 'c' ] as SortedSet
           assert strings.dropRight( 0 ) == [ 'a', 'b', 'c' ] as SortedSet
           assert strings.dropRight( 2 ) == [ 'a' ] as SortedSet
           assert strings.dropRight( 5 ) == [] as SortedSet

      Parameters:
        `num` - the number of elements to drop from this SortedSet
      Returns:
        a List consisting of all the elements of this SortedSet minus the last `num` elements, or an empty SortedSet if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public SortedSet<T> dropWhile(Closure condition)

      Returns a suffix of this SortedSet where elements are dropped from the front while the given Closure evaluates to true. Similar to Iterable#dropWhile(groovy.lang.Closure) except that it attempts to preserve the type of the original SortedSet.

           def nums = [ 1, 2, 3 ] as SortedSet
           assert nums.dropWhile{ it < 4 } == [] as SortedSet
           assert nums.dropWhile{ it < 2 } == [ 2, 3 ] as SortedSet
           assert nums.dropWhile{ it != 3 } == [ 3 ] as SortedSet
           assert nums.dropWhile{ it == 0 } == [ 1, 2, 3 ] as SortedSet

      Parameters:
        `condition` - the closure that must evaluate to true to continue dropping elements
      Returns:
        the shortest suffix of the given SortedSet such that the given closure condition evaluates to true for each element dropped from the front of the SortedSet
      Since:
        2.4.0

    - #### <T> public SortedSet<T> each(Closure closure)

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

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

    - #### <T> public SortedSet<T> eachWithIndex(Closure closure)

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

    - #### <T, E> public SortedSet<T> flatten()

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

           Set nested = [[0,1],[2],3,[4],5]
           SortedSet sorted = new TreeSet({ a, b -> (a instanceof List ? a[0] : a) <=> (b instanceof List ? b[0] : b) } as Comparator)
           sorted.addAll(nested)
           assert [0,1,2,3,4,5] as SortedSet == sorted.flatten()

      Returns:
        a flattened SortedSet
      Since:
        2.4.0

    - #### <T> public SortedSet<T> init()

      Returns the items from the SortedSet excluding the last item. Leaves the original SortedSet unchanged.

           def sortedSet = [3, 4, 2] as SortedSet
           assert sortedSet.init() == [2, 3] as SortedSet
           assert sortedSet == [3, 4, 2] as SortedSet

      throws:
        NoSuchElementException if you try to access init() for an empty SortedSet
      Returns:
        a SortedSet without its last element
      Since:
        2.4.0

    - #### <T> public SortedSet<T> intersect(Iterable<T> right)

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

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

    - #### <T> public SortedSet<T> intersect(Iterable<T> right, Comparator<? super T> comparator)

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

           assert [4,5] as SortedSet == ([1,2,3,4,5] as SortedSet).intersect([4,5,6,7,8])

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

    - #### <T> public SortedSet<T> leftShift(T value)

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

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

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

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

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

      Parameters:
        `removeMe` - the elements to exclude
      Returns:
        a new SortedSet
      Since:
        2.4.0

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

      Create a SortedSet composed of the elements of the first SortedSet minus the elements of the given Iterable.

      Parameters:
        `removeMe` - the elements to exclude
      Returns:
        a new SortedSet
      Since:
        2.4.0

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

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

      Parameters:
        `removeMe` - the element to exclude
      Returns:
        a new SortedSet
      Since:
        2.4.0

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

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

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

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

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

    - #### <T> public SortedSet<T> plus(Iterable<T> right)

      Create a SortedSet as a union of a SortedSet 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 SortedSet
      Since:
        2.4.0
      See Also:
        plus(Collection, Collection)

    - #### <T> public SortedSet<T> plus(Collection<T> right)

      Create a SortedSet as a union of a SortedSet 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 SortedSet
      Since:
        2.4.0
      See Also:
        plus(Collection, Collection)

    - #### <T> public SortedSet<T> plus(T right)

      Create a SortedSet as a union of a SortedSet 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 SortedSet
      Since:
        2.4.0

    - #### <T> public SortedSet<T> sort()

      Avoids doing unnecessary work when sorting an already sorted set (i.e. an identity function for an already sorted set).

      Returns:
        the set
      Since:
        1.0

    - #### <T> public SortedSet<T> tail()

      Returns the items from the SortedSet excluding the first item.

           def sortedSet = [3, 4, 2] as SortedSet
           assert sortedSet.tail() == [3, 4] as SortedSet
           assert sortedSet == [3, 4, 2] as SortedSet

      throws:
        NoSuchElementException if you try to access tail() for an empty SortedSet
      Returns:
        a SortedSet without its first element
      Since:
        2.4.0

    - #### <T> public SortedSet<T> take(int num)

      Returns the first `num` elements from the head of this SortedSet.

           def strings = [ 'a', 'b', 'c' ] as SortedSet
           assert strings.take( 0 ) == [] as SortedSet
           assert strings.take( 2 ) == [ 'a', 'b' ] as SortedSet
           assert strings.take( 5 ) == [ 'a', 'b', 'c' ] as SortedSet

      Parameters:
        `num` - the number of elements to take from this SortedSet
      Returns:
        a SortedSet consisting of the first `num` elements from this List, or else all the elements from the SortedSet if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public SortedSet<T> takeRight(int num)

      Returns the last `num` elements from the tail of this SortedSet.

           def strings = [ 'a', 'b', 'c' ] as SortedSet
           assert strings.takeRight( 0 ) == [] as SortedSet
           assert strings.takeRight( 2 ) == [ 'b', 'c' ] as SortedSet
           assert strings.takeRight( 5 ) == [ 'a', 'b', 'c' ] as SortedSet

      Parameters:
        `num` - the number of elements to take from this SortedSet
      Returns:
        a SortedSet consisting of the last `num` elements from this SortedSet, or else all the elements from the SortedSet if it has less than `num` elements.
      Since:
        2.4.0

    - #### <T> public SortedSet<T> takeWhile(Closure condition)

      Returns the longest prefix of this SortedSet where each element passed to the given closure condition evaluates to true. Similar to Iterable#takeWhile(groovy.lang.Closure) except that it attempts to preserve the type of the original SortedSet.

           def nums = [ 1, 2, 3 ] as SortedSet
           assert nums.takeWhile{ it < 1 } == [] as SortedSet
           assert nums.takeWhile{ it < 2 } == [ 1 ] as SortedSet
           assert nums.takeWhile{ it < 4 } == [ 1, 2, 3 ] as SortedSet

      Parameters:
        `condition` - the closure that must evaluate to true to continue taking elements
      Returns:
        a prefix of the given SortedSet where each element passed to the given closure evaluates to true
      Since:
        2.4.0

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

      Avoids doing unnecessary work when sorting an already sorted set

      Returns:
        an ordered copy of the sorted set
      Since:
        2.4.0

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

      Create a SortedSet composed of the union of a SortedSet 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 SortedSet == ([1,2,3,4,5] as SortedSet).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 SortedSet and an Iterable
      See Also:
        intersect(SortedSet, Iterable, Comparator)
      Since:
        5.0.0

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

      Create a SortedSet composed of the intersection of a SortedSet 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 SortedSet == ([1,2,3,4,5] as SortedSet).union([4,5,6,7,8])

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

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

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

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

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

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

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

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

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

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

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