SortedSet (Groovy JDK enhancements)

Package: java.util

## Interface SortedSet

- - ### Methods Summary

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

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

    `and`, `and`, `asChecked`, `asImmutable`, `asSynchronized`, `asUnmodifiable`, `each`, `eachWithIndex`, `equals`, `findAll`, `findAll`, `flatten`, `grep`, `grep`, `intersect`, `intersect`, `leftShift`, `minus`, `minus`, `minus`, `or`, `plus`, `plus`, `plus`, `split`, `union`, `union`, `xor`, `xor`

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

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

  - #### 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 SortedSet and(Iterable 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
      Since:
        5.0.0
      See Also:
        Set#intersect(Iterable)

    - #### public SortedSet and(Iterable right, Comparator 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
      Since:
        5.0.0
      See Also:
        SortedSet#intersect(Iterable, Comparator)

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

      Creates a checked view of a SortedSet.

      Parameters:
      Since:
        5.0.0
      See Also:
        Collections#checkedSortedSet

    - #### public SortedSet 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
      Since:
        1.0
      See Also:
        List#asImmutable()
        SortedSet#asUnmodifiable()

    - #### public SortedSet asSynchronized()

      Creates a synchronized view of a SortedSet.

      Returns:
        a synchronized SortedSet
      Since:
        1.0
      See Also:
        Collections#synchronizedSortedSet(java.util.SortedSet)

    - #### public SortedSet asUnmodifiable()

      Creates an unmodifiable view of a SortedSet.

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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

      Returns:
        a SortedSet without its last element
      Since:
        2.4.0

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

    - #### public SortedSet intersect(Iterable right, Comparator 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

    - #### public SortedSet leftShift(Object 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

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

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

      Parameters:
        `removeMe` - the items to remove from the SortedSet
      Returns:
        the resulting SortedSet
      Since:
        2.4.0

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

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

      Parameters:
        `removeMe` - the element to remove from the SortedSet
      Returns:
        the resulting SortedSet
      Since:
        2.4.0

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

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

      Parameters:
        `removeMe` - the items to remove from the SortedSet
      Returns:
        the resulting SortedSet
      Since:
        2.4.0

    - #### public SortedSet or(Iterable 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:
        SortedSet#plus(Iterable)

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

    - #### public SortedSet plus(Object 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

    - #### public SortedSet plus(Collection 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:
        Collection#plus(Collection)

    - #### public SortedSet 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

    - #### public SortedSet 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

      Returns:
        a SortedSet without its first element
      Since:
        2.4.0

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public SortedSet 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

    - #### public Set toSorted()

      Avoids doing unnecessary work when sorting an already sorted set

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

    - #### public SortedSet union(Iterable 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
      Since:
        5.0.0
      See Also:
        SortedSet#intersect(Iterable, Comparator)

    - #### public SortedSet union(Iterable right, Comparator 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

    - #### public SortedSet xor(Iterable 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

    - #### public SortedSet xor(Iterable right, Comparator 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