# Class TreeSet<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractSet<E>
java.util.TreeSet<E>

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, NavigableSet<E>, Set<E>, SortedSet<E>`

public class TreeSet<E> extends AbstractSet<E> implements NavigableSet<E>

TreeSet is an implementation of SortedSet. All optional operations (adding and removing) are supported. The elements can be any objects which are comparable to each other either using their natural order or a specified Comparator.

##### Since

1.2

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TreeSet()`
  Constructs a new empty instance of `TreeSet` which uses natural ordering.
  `TreeSet(Collection<? extends E> collection)`
  Constructs a new instance of `TreeSet` which uses natural ordering and containing the unique elements in the specified collection.
  `TreeSet(Comparator<? super E> comparator)`
  Constructs a new empty instance of `TreeSet` which uses the specified comparator.
  `TreeSet(SortedSet<E> set)`
  Constructs a new instance of `TreeSet` containing the elements of the specified SortedSet and using the same Comparator.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Adds the specified object to this `TreeSet`.
  `boolean`
  `addAll(Collection<? extends E> collection)`
  Adds the objects in the specified collection to this `TreeSet`.
  `E`
  `ceiling(E e)`
  Answers the smallest element bigger than or equal to the specified one, or null if no such element.
  `void`
  `clear()`
  Removes all elements from this `TreeSet`, leaving it empty.
  `Comparator<? super E>`
  `comparator()`
  Returns the comparator used to compare elements in this `TreeSet`.
  `boolean`
  `contains(Object object)`
  Searches this `TreeSet` for the specified object.
  `Iterator<E>`
  `descendingIterator()`
  Answers a descending iterator of this set.
  `NavigableSet<E>`
  `descendingSet()`
  Answers a reverse order view of this set.
  `E`
  `first()`
  Answers the first element in this TreeSet.
  `E`
  `floor(E e)`
  Answers the biggest element less than or equal to the specified one, or null if no such element.
  `SortedSet<E>`
  `headSet(E end)`
  Answers a SortedSet of the specified portion of this TreeSet which contains elements less than the end element.
  `NavigableSet<E>`
  `headSet(E end, boolean endInclusive)`
  Answers a NavigableSet of the specified portion of this set which contains elements less than (or equal to, depends on endInclusive) the end element.
  `E`
  `higher(E e)`
  Answers the smallest element bigger than the specified one, or null if no such element.
  `boolean`
  `isEmpty()`
  Returns true if this `TreeSet` has no element, otherwise false.
  `Iterator<E>`
  `iterator()`
  Returns an Iterator on the elements of this `TreeSet`.
  `E`
  `last()`
  Answers the last element in this TreeSet.
  `E`
  `lower(E e)`
  Answers the biggest element less than the specified one, or null if no such element.
  `E`
  `pollFirst()`
  Deletes and answers the smallest element, or null if the set is empty.
  `E`
  `pollLast()`
  Deletes and answers the biggest element, or null if the set is empty.
  `boolean`
  `remove(Object object)`
  Removes an occurrence of the specified object from this `TreeSet`.
  `int`
  `size()`
  Returns the number of elements in this `TreeSet`.
  `NavigableSet<E>`
  `subSet(E start, boolean startInclusive, E end, boolean endInclusive)`
  Answers a NavigableSet of the specified portion of this set which contains elements greater (or equal to, depends on startInclusive) the start element but less than (or equal to, depends on endInclusive) the end element.
  `SortedSet<E>`
  `subSet(E start, E end)`
  Answers a SortedSet of the specified portion of this TreeSet which contains elements greater or equal to the start element but less than the end element.
  `SortedSet<E>`
  `tailSet(E start)`
  Answers a SortedSet of the specified portion of this TreeSet which contains elements greater or equal to the start element.
  `NavigableSet<E>`
  `tailSet(E start, boolean startInclusive)`
  Answers a NavigableSet of the specified portion of this set which contains elements greater (or equal to, depends on startInclusive) the start element.

  ### Methods inherited from class AbstractSet

  `equals, hashCode, removeAll`

  ### Methods inherited from class AbstractCollection

  `containsAll, retainAll, toArray, toArray, toString`

  ### Methods inherited from class Object

  `clone, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Set

  `containsAll, equals, hashCode, removeAll, retainAll, toArray, toArray`

- ## Constructor Details

  - ### TreeSet

    public TreeSet()
    Constructs a new empty instance of `TreeSet` which uses natural ordering.

  - ### TreeSet

    public TreeSet(Collection<? extends E> collection)

    Constructs a new instance of `TreeSet` which uses natural ordering and containing the unique elements in the specified collection.

    ###### Parameters

    - `collection`: the collection of elements to add.

    ###### Throws

    - `ClassCastException`: @throws ClassCastException when an element in the collection does not implement the Comparable interface, or the elements in the collection cannot be compared.

  - ### TreeSet

    public TreeSet(Comparator<? super E> comparator)

    Constructs a new empty instance of `TreeSet` which uses the specified comparator.

    ###### Parameters

    - `comparator`: the comparator to use.

  - ### TreeSet

    public TreeSet(SortedSet<E> set)

    Constructs a new instance of `TreeSet` containing the elements of the specified SortedSet and using the same Comparator.

    ###### Parameters

    - `set`: the SortedSet of elements to add.

- ## Method Details

  - ### add

    public boolean add(E object)

    Adds the specified object to this `TreeSet`.

    ###### Parameters

    - `object`: the object to add.

    ###### Returns

    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `Set<E>`
    Overrides:
      `add` in class `AbstractCollection<E>`
    Returns:

      `true` when this `TreeSet` did not already contain the object, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException when the object cannot be compared with the elements in this `TreeSet`.

      - `NullPointerException`: @throws NullPointerException when the object is null and the comparator cannot handle null.

  - ### addAll

    public boolean addAll(Collection<? extends E> collection)

    Adds the objects in the specified collection to this `TreeSet`.

    ###### Parameters

    - `collection`: the collection of objects to add.

    ###### Returns

    Specified by:
      `addAll` in interface `Collection<E>`
    Specified by:
      `addAll` in interface `Set<E>`
    Overrides:
      `addAll` in class `AbstractCollection<E>`
    Returns:

      `true` if this `TreeSet` was modified, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException when an object in the collection cannot be compared with the elements in this `TreeSet`.

      - `NullPointerException`: @throws NullPointerException when an object in the collection is null and the comparator cannot handle null.

  - ### clear

    public void clear()

    Removes all elements from this `TreeSet`, leaving it empty.

    ###### See also

    - #isEmpty

    - #size

    Specified by:
      `clear` in interface `Collection<E>`
    Specified by:
      `clear` in interface `Set<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`

  - ### comparator

    public Comparator<? super E> comparator()

    Returns the comparator used to compare elements in this `TreeSet`.

    ###### Returns

    a Comparator or null if the natural ordering is used

    Specified by:
      `comparator` in interface `SortedSet<E>`

  - ### contains

    public boolean contains(Object object)

    Searches this `TreeSet` for the specified object.

    ###### Parameters

    - `object`: the object to search for.

    ###### Returns

    Specified by:
      `contains` in interface `Collection<E>`
    Specified by:
      `contains` in interface `Set<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Returns:

      `true` if `object` is an element of this `TreeSet`, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException when the object cannot be compared with the elements in this `TreeSet`.

      - `NullPointerException`: @throws NullPointerException when the object is null and the comparator cannot handle null.

  - ### isEmpty

    public boolean isEmpty()

    Returns true if this `TreeSet` has no element, otherwise false.

    ###### Returns

    true if this `TreeSet` has no element.

    ###### See also

    - #size
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Specified by:
      `isEmpty` in interface `Set<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:

      `true` if this `Collection` has no elements, `false` otherwise.

      ###### See also

      - #size

  - ### iterator

    public Iterator<E> iterator()

    Returns an Iterator on the elements of this `TreeSet`.

    ###### Returns

    an Iterator on the elements of this `TreeSet`.

    ###### See also

    - Iterator
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in interface `Set<E>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`

  - ### descendingIterator

    public Iterator<E> descendingIterator()

    Answers a descending iterator of this set.

    ###### Returns

    the descending iterator

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#descendingIterator()
    Specified by:
      `descendingIterator` in interface `NavigableSet<E>`

  - ### remove

    public boolean remove(Object object)

    Removes an occurrence of the specified object from this `TreeSet`.

    ###### Parameters

    - `object`: the object to remove.

    ###### Returns

    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `Set<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Returns:

      `true` if this `TreeSet` was modified, `false` otherwise.

      ###### Throws

      - `ClassCastException`: @throws ClassCastException when the object cannot be compared with the elements in this `TreeSet`.

      - `NullPointerException`: @throws NullPointerException when the object is null and the comparator cannot handle null.

  - ### size

    public int size()

    Returns the number of elements in this `TreeSet`.

    ###### Returns

    the number of elements in this `TreeSet`.

    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in interface `Set<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      how many objects this `Collection` contains, or `Integer.MAX_VALUE` if there are more than `Integer.MAX_VALUE` elements in this `Collection`.

  - ### first

    public E first()

    Answers the first element in this TreeSet.

    ###### Returns

    the first element

    ###### Throws

    - `NoSuchElementException`: when this TreeSet is empty
    Specified by:
      `first` in interface `SortedSet<E>`

  - ### last

    public E last()

    Answers the last element in this TreeSet.

    ###### Returns

    the last element

    ###### Throws

    - `NoSuchElementException`: when this TreeSet is empty
    Specified by:
      `last` in interface `SortedSet<E>`

  - ### pollFirst

    public E pollFirst()

    Deletes and answers the smallest element, or null if the set is empty.

    ###### Returns

    the smallest element, or null if the set is empty

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#pollFirst()
    Specified by:
      `pollFirst` in interface `NavigableSet<E>`

  - ### pollLast

    public E pollLast()

    Deletes and answers the biggest element, or null if the set is empty.

    ###### Returns

    the biggest element, or null if the set is empty

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#pollLast()
    Specified by:
      `pollLast` in interface `NavigableSet<E>`

  - ### higher

    public E higher(E e)

    Answers the smallest element bigger than the specified one, or null if no such element.

    ###### Parameters

    - `e`: the specified element

    ###### Returns

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#higher(java.lang.Object)
    Specified by:
      `higher` in interface `NavigableSet<E>`
    Returns:

      the smallest element bigger than the specified one, or null if no such element

      ###### Throws

      - `ClassCastException`: if the element cannot be compared with the ones in the set

      - `NullPointerException`: if the element is null and the set can not contain null

  - ### lower

    public E lower(E e)

    Answers the biggest element less than the specified one, or null if no such element.

    ###### Parameters

    - `e`: the specified element

    ###### Returns

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#lower(java.lang.Object)
    Specified by:
      `lower` in interface `NavigableSet<E>`
    Returns:

      the biggest element less than the specified one, or null if no such element

      ###### Throws

      - `ClassCastException`: if the element cannot be compared with the ones in the set

      - `NullPointerException`: if the element is null and the set can not contain null

  - ### ceiling

    public E ceiling(E e)

    Answers the smallest element bigger than or equal to the specified one, or null if no such element.

    ###### Parameters

    - `e`: the specified element

    ###### Returns

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#ceiling(java.lang.Object)
    Specified by:
      `ceiling` in interface `NavigableSet<E>`
    Returns:

      the smallest element bigger than or equal to the specified one, or null if no such element

      ###### Throws

      - `ClassCastException`: if the element cannot be compared with the ones in the set

      - `NullPointerException`: if the element is null and the set can not contain null

  - ### floor

    public E floor(E e)

    Answers the biggest element less than or equal to the specified one, or null if no such element.

    ###### Parameters

    - `e`: the specified element

    ###### Returns

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#floor(java.lang.Object)
    Specified by:
      `floor` in interface `NavigableSet<E>`
    Returns:

      the biggest element less than or equal to the specified one, or null if no such element

      ###### Throws

      - `ClassCastException`: if the element cannot be compared with the ones in the set

      - `NullPointerException`: if the element is null and the set can not contain null

  - ### descendingSet

    public NavigableSet<E> descendingSet()

    Answers a reverse order view of this set.

    ###### Returns

    the reverse order view

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#descendingSet()
    Specified by:
      `descendingSet` in interface `NavigableSet<E>`

  - ### subSet

    public NavigableSet<E> subSet(E start, boolean startInclusive, E end, boolean endInclusive)

    Answers a NavigableSet of the specified portion of this set which contains elements greater (or equal to, depends on startInclusive) the start element but less than (or equal to, depends on endInclusive) the end element. The returned NavigableSet is backed by this set so changes to one are reflected by the other.

    ###### Parameters

    - `start`: the start element

    - `startInclusive`: true if the start element is in the returned set

    - `end`: the end element

    - `endInclusive`: true if the end element is in the returned set

    ###### Returns

    the subset

    ###### Throws

    - `ClassCastException`: @throws ClassCastException when the start or end object cannot be compared with the elements in this set

    - `NullPointerException`: @throws NullPointerException when the start or end object is null and the set cannot contain null

    - `IllegalArgumentException`: @throws IllegalArgumentException when the start is bigger than end; or start or end is out of range and the set has a range

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#subSet(Object, boolean, Object, boolean)
    Specified by:
      `subSet` in interface `NavigableSet<E>`

  - ### headSet

    public NavigableSet<E> headSet(E end, boolean endInclusive)

    Answers a NavigableSet of the specified portion of this set which contains elements less than (or equal to, depends on endInclusive) the end element. The returned NavigableSet is backed by this set so changes to one are reflected by the other.

    ###### Parameters

    - `end`: the end element

    - `endInclusive`: true if the end element is in the returned set

    ###### Returns

    the subset

    ###### Throws

    - `ClassCastException`: @throws ClassCastException when the end object cannot be compared with the elements in this set

    - `NullPointerException`: @throws NullPointerException when the end object is null and the set cannot contain handle null

    - `IllegalArgumentException`: when end is out of range and the set has a range

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#headSet(Object, boolean)
    Specified by:
      `headSet` in interface `NavigableSet<E>`

  - ### tailSet

    public NavigableSet<E> tailSet(E start, boolean startInclusive)

    Answers a NavigableSet of the specified portion of this set which contains elements greater (or equal to, depends on startInclusive) the start element. The returned NavigableSet is backed by this set so changes to one are reflected by the other.

    ###### Parameters

    - `start`: the start element

    - `startInclusive`: true if the start element is in the returned set

    ###### Returns

    the subset

    ###### Throws

    - `ClassCastException`: @throws ClassCastException when the start object cannot be compared with the elements in this set

    - `NullPointerException`: when the start object is null and the set cannot contain null

    - `IllegalArgumentException`: when start is out of range and the set has a range

    ###### Since

    1.6

    ###### See also

    - java.util.NavigableSet#tailSet(Object, boolean)
    Specified by:
      `tailSet` in interface `NavigableSet<E>`

  - ### subSet

    public SortedSet<E> subSet(E start, E end)

    Answers a SortedSet of the specified portion of this TreeSet which contains elements greater or equal to the start element but less than the end element. The returned SortedSet is backed by this TreeSet so changes to one are reflected by the other.

    ###### Parameters

    - `start`: the start element

    - `end`: the end element

    ###### Returns

    Specified by:
      `subSet` in interface `SortedSet<E>`
    Returns:

      a subset where the elements are greater or equal to `start` and less than `end`

      ###### Throws

      - `ClassCastException`: @exception ClassCastException when the start or end object cannot be compared with the elements in this TreeSet

      - `NullPointerException`: @exception NullPointerException when the start or end object is null and the comparator cannot handle null

  - ### headSet

    public SortedSet<E> headSet(E end)

    Answers a SortedSet of the specified portion of this TreeSet which contains elements less than the end element. The returned SortedSet is backed by this TreeSet so changes to one are reflected by the other.

    ###### Parameters

    - `end`: the end element

    ###### Returns

    a subset where the elements are less than `end`

    ###### Throws

    - `ClassCastException`: @exception ClassCastException when the end object cannot be compared with the elements in this TreeSet

    - `NullPointerException`: @exception NullPointerException when the end object is null and the comparator cannot handle null

    Specified by:
      `headSet` in interface `SortedSet<E>`

  - ### tailSet

    public SortedSet<E> tailSet(E start)

    Answers a SortedSet of the specified portion of this TreeSet which contains elements greater or equal to the start element. The returned SortedSet is backed by this TreeSet so changes to one are reflected by the other.

    ###### Parameters

    - `start`: the start element

    ###### Returns

    Specified by:
      `tailSet` in interface `SortedSet<E>`
    Returns:

      a subset where the elements are greater or equal to `start`

      ###### Throws

      - `ClassCastException`: @exception ClassCastException when the start object cannot be compared with the elements in this TreeSet

      - `NullPointerException`: @exception NullPointerException when the start object is null and the comparator cannot handle null