# 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` - 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`.
    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `Set<E>`
    Overrides:
      `add` in class `AbstractCollection<E>`
    Parameters:
      `object` - the object to add.
    Returns:
      `true` when this `TreeSet` did not already contain the object, `false` otherwise.
    Throws:
      `ClassCastException` - when the object cannot be compared with the elements in this `TreeSet`.
      `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`.
    Specified by:
      `addAll` in interface `Collection<E>`
    Specified by:
      `addAll` in interface `Set<E>`
    Overrides:
      `addAll` in class `AbstractCollection<E>`
    Parameters:
      `collection` - the collection of objects to add.
    Returns:
      `true` if this `TreeSet` was modified, `false` otherwise.
    Throws:
      `ClassCastException` - when an object in the collection cannot be compared with the elements in this `TreeSet`.
      `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.
    Specified by:
      `clear` in interface `Collection<E>`
    Specified by:
      `clear` in interface `Set<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`
    See Also:
      - `isEmpty()`
      - `size()`

  - ### comparator

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

  - ### contains

    public boolean contains(Object object)
    Searches this `TreeSet` for the specified object.
    Specified by:
      `contains` in interface `Collection<E>`
    Specified by:
      `contains` in interface `Set<E>`
    Overrides:
      `contains` in class `AbstractCollection<E>`
    Parameters:
      `object` - the object to search for.
    Returns:
      `true` if `object` is an element of this `TreeSet`, `false` otherwise.
    Throws:
      `ClassCastException` - when the object cannot be compared with the elements in this `TreeSet`.
      `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.
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Specified by:
      `isEmpty` in interface `Set<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:
      true if this `TreeSet` has no element.
    See Also:
      - `size()`

  - ### iterator

    public Iterator<E> iterator()
    Returns an Iterator on the elements of this `TreeSet`.
    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>`
    Returns:
      an Iterator on the elements of this `TreeSet`.
    See Also:
      - `Iterator`

  - ### descendingIterator

    public Iterator<E> descendingIterator()
    Answers a descending iterator of this set.
    Specified by:
      `descendingIterator` in interface `NavigableSet<E>`
    Returns:
      the descending iterator
    Since:
      1.6
    See Also:
      - `NavigableSet.descendingIterator()`

  - ### remove

    public boolean remove(Object object)
    Removes an occurrence of the specified object from this `TreeSet`.
    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `Set<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Parameters:
      `object` - the object to remove.
    Returns:
      `true` if this `TreeSet` was modified, `false` otherwise.
    Throws:
      `ClassCastException` - when the object cannot be compared with the elements in this `TreeSet`.
      `NullPointerException` - when the object is null and the comparator cannot handle null.

  - ### size

    public int size()
    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:
      the number of elements in this `TreeSet`.

  - ### first

    public E first()
    Answers the first element in this TreeSet.
    Specified by:
      `first` in interface `SortedSet<E>`
    Returns:
      the first element
    Throws:
      `NoSuchElementException` - when this TreeSet is empty

  - ### last

    public E last()
    Answers the last element in this TreeSet.
    Specified by:
      `last` in interface `SortedSet<E>`
    Returns:
      the last element
    Throws:
      `NoSuchElementException` - when this TreeSet is empty

  - ### pollFirst

    public E pollFirst()
    Deletes and answers the smallest element, or null if the set is empty.
    Specified by:
      `pollFirst` in interface `NavigableSet<E>`
    Returns:
      the smallest element, or null if the set is empty
    Since:
      1.6
    See Also:
      - `NavigableSet.pollFirst()`

  - ### pollLast

    public E pollLast()
    Deletes and answers the biggest element, or null if the set is empty.
    Specified by:
      `pollLast` in interface `NavigableSet<E>`
    Returns:
      the biggest element, or null if the set is empty
    Since:
      1.6
    See Also:
      - `NavigableSet.pollLast()`

  - ### higher

    public E higher(E e)
    Answers the smallest element bigger than the specified one, or null if no such element.
    Specified by:
      `higher` in interface `NavigableSet<E>`
    Parameters:
      `e` - the specified element
    Returns:
      the smallest element bigger than the specified one, or null if no such element
    Since:
      1.6
    See Also:
      - `NavigableSet.higher(java.lang.Object)`

  - ### lower

    public E lower(E e)
    Answers the biggest element less than the specified one, or null if no such element.
    Specified by:
      `lower` in interface `NavigableSet<E>`
    Parameters:
      `e` - the specified element
    Returns:
      the biggest element less than the specified one, or null if no such element
    Since:
      1.6
    See Also:
      - `NavigableSet.lower(java.lang.Object)`

  - ### ceiling

    public E ceiling(E e)
    Answers the smallest element bigger than or equal to the specified one, or null if no such element.
    Specified by:
      `ceiling` in interface `NavigableSet<E>`
    Parameters:
      `e` - the specified element
    Returns:
      the smallest element bigger than or equal to the specified one, or null if no such element
    Since:
      1.6
    See Also:
      - `NavigableSet.ceiling(java.lang.Object)`

  - ### floor

    public E floor(E e)
    Answers the biggest element less than or equal to the specified one, or null if no such element.
    Specified by:
      `floor` in interface `NavigableSet<E>`
    Parameters:
      `e` - the specified element
    Returns:
      the biggest element less than or equal to the specified one, or null if no such element
    Since:
      1.6
    See Also:
      - `NavigableSet.floor(java.lang.Object)`

  - ### descendingSet

    public NavigableSet<E> descendingSet()
    Answers a reverse order view of this set.
    Specified by:
      `descendingSet` in interface `NavigableSet<E>`
    Returns:
      the reverse order view
    Since:
      1.6
    See Also:
      - `NavigableSet.descendingSet()`

  - ### 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.
    Specified by:
      `subSet` in interface `NavigableSet<E>`
    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
    Since:
      1.6
    See Also:
      - `NavigableSet.subSet(Object, boolean, Object, boolean)`

  - ### 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.
    Specified by:
      `headSet` in interface `NavigableSet<E>`
    Parameters:
      `end` - the end element
      `endInclusive` - true if the end element is in the returned set
    Returns:
      the subset
    Since:
      1.6
    See Also:
      - `NavigableSet.headSet(Object, boolean)`

  - ### 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.
    Specified by:
      `tailSet` in interface `NavigableSet<E>`
    Parameters:
      `start` - the start element
      `startInclusive` - true if the start element is in the returned set
    Returns:
      the subset
    Since:
      1.6
    See Also:
      - `NavigableSet.tailSet(Object, boolean)`

  - ### 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.
    Specified by:
      `subSet` in interface `SortedSet<E>`
    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 start or end object cannot be compared with the elements in this TreeSet
      `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.
    Specified by:
      `headSet` in interface `SortedSet<E>`
    Parameters:
      `end` - the end element
    Returns:
      a subset where the elements are less than `end`
    Throws:
      `ClassCastException` - when the end object cannot be compared with the elements in this TreeSet
      `NullPointerException` - when the end object is null and the comparator cannot handle null

  - ### 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.
    Specified by:
      `tailSet` in interface `SortedSet<E>`
    Parameters:
      `start` - the start element
    Returns:
      a subset where the elements are greater or equal to `start`
    Throws:
      `ClassCastException` - when the start object cannot be compared with the elements in this TreeSet
      `NullPointerException` - when the start object is null and the comparator cannot handle null