# Interface SortedSet<E>

All Superinterfaces:
  `Collection<E>, Iterable<E>, Set<E>`

All Known Subinterfaces:
  `NavigableSet<E>`

All Known Implementing Classes:
  `TreeSet`

public interface SortedSet<E> extends Set<E>
SortedSet is a Set which iterates over its elements in a sorted order. The order is determined either by the elements natural ordering, or by a `Comparator` which is passed into a concrete implementation at construction time. All elements in this set must be mutually comparable. The ordering in this set must be consistent with `equals` of its elements.

See Also:
  - `Comparator`
  - `Comparable`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Comparator<? super E>`
  `comparator()`
  Returns the comparator used to compare elements in this `SortedSet`.
  `E`
  `first()`
  Returns the first element in this `SortedSet`.
  `SortedSet<E>`
  `headSet(E end)`
  Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements less than the end element.
  `E`
  `last()`
  Returns the last element in this `SortedSet`.
  `SortedSet<E>`
  `subSet(E start, E end)`
  Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements greater or equal to the start element but less than the end element.
  `SortedSet<E>`
  `tailSet(E start)`
  Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements greater or equal to the start element.

  ### Methods inherited from interface Set

  `add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray`
  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Adds the specified object to this set.
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Adds the objects in the specified collection which do not exist yet in this set.
  `void`
  `clear()`
  Removes all elements from this set, leaving it empty.
  `boolean`
  `contains(Object object)`
  Searches this set for the specified object.
  `boolean`
  `containsAll(Collection<?> collection)`
  Searches this set for all objects in the specified collection.
  `boolean`
  `equals(Object object)`
  Compares the specified object to this set, and returns true if they represent the same object using a class specific comparison.
  `int`
  `hashCode()`
  Returns the hash code for this set.
  `boolean`
  `isEmpty()`
  Returns true if this set has no elements.
  `Iterator<E>`
  `iterator()`
  Returns an iterator on the elements of this set.
  `boolean`
  `remove(Object object)`
  Removes the specified object from this set.
  `boolean`
  `removeAll(Collection<?> collection)`
  Removes all objects in the specified collection from this set.
  `boolean`
  `retainAll(Collection<?> collection)`
  Removes all objects from this set that are not contained in the specified collection.
  `int`
  `size()`
  Returns the number of elements in this set.
  `Object[]`
  `toArray()`
  Returns an array containing all elements contained in this set.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array containing all elements contained in this set.

- ## Method Details

  - ### comparator

    Comparator<? super E> comparator()
    Returns the comparator used to compare elements in this `SortedSet`.
    Returns:
      a comparator or null if the natural ordering is used.

  - ### first

    E first()
    Returns the first element in this `SortedSet`. The first element is the lowest element.
    Returns:
      the first element.
    Throws:
      `NoSuchElementException` - when this `SortedSet` is empty.

  - ### headSet

    SortedSet<E> headSet(E end)
    Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements less than the end element. The returned `SortedSet` is backed by this `SortedSet` so changes to one set are reflected by the other.
    Parameters:
      `end` - the end element.
    Returns:
      a subset where the elements are less than `end`.
    Throws:
      `ClassCastException` - when the class of the end element is inappropriate for this SubSet.
      `NullPointerException` - when the end element is null and this `SortedSet` does not support null elements.

  - ### last

    E last()
    Returns the last element in this `SortedSet`. The last element is the highest element.
    Returns:
      the last element.
    Throws:
      `NoSuchElementException` - when this `SortedSet` is empty.

  - ### subSet

    SortedSet<E> subSet(E start, E end)
    Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements greater or equal to the start element but less than the end element. The returned `SortedSet` is backed by this SortedMap so changes to one set are reflected by the other.
    Parameters:
      `start` - the start element.
      `end` - the end element.
    Returns:
      a subset where the elements are greater or equal to `start` and less than `end`.
    Throws:
      `ClassCastException` - when the class of the start or end element is inappropriate for this SubSet.
      `NullPointerException` - when the start or end element is null and this `SortedSet` does not support null elements.
      `IllegalArgumentException` - when the start element is greater than the end element.

  - ### tailSet

    SortedSet<E> tailSet(E start)
    Returns a `SortedSet` of the specified portion of this `SortedSet` which contains elements greater or equal to the start element. The returned `SortedSet` is backed by this `SortedSet` so changes to one set are reflected by the other.
    Parameters:
      `start` - the start element.
    Returns:
      a subset where the elements are greater or equal to `start` .
    Throws:
      `ClassCastException` - when the class of the start element is inappropriate for this SubSet.
      `NullPointerException` - when the start element is null and this `SortedSet` does not support null elements.