# Interface NavigableSet<E>

Type Parameters:
  `E` - the type of element

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

All Known Implementing Classes:
  `TreeSet`

public interface NavigableSet<E> extends SortedSet<E>
NavigableSet is a SortedSet with navigation methods answering the closest matches for specified item.

Since:
  1.6

- ## Method Summary

  Modifier and Type
  Method
  Description
  `E`
  `ceiling(E e)`
  Answers the smallest element bigger than or equal to the specified one, or null if no such element.
  `Iterator<E>`
  `descendingIterator()`
  Answers a descending iterator of this set.
  `NavigableSet<E>`
  `descendingSet()`
  Answers a reverse order view of this set.
  `E`
  `floor(E e)`
  Answers the biggest element less than or equal to the specified one, or null if no such 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.
  `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.
  `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.
  `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 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.

  ### Methods inherited from interface SortedSet

  `comparator, first, headSet, last, subSet, tailSet`
  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.

- ## Method Details

  - ### pollFirst

    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

  - ### pollLast

    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

  - ### higher

    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:
      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

  - ### ceiling

    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:
      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

  - ### lower

    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:
      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

  - ### floor

    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:
      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

  - ### descendingIterator

    Iterator<E> descendingIterator()
    Answers a descending iterator of this set.
    Returns:
      the descending iterator

  - ### descendingSet

    NavigableSet<E> descendingSet()
    Answers a reverse order view of this set.
    Returns:
      the reverse order view

  - ### subSet

    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` - when the start or end object cannot be compared with the elements in this set
      `NullPointerException` - when the start or end object is null and the set cannot contain null
      `IllegalArgumentException` - when the start is bigger than end; or start or end is out of range and the set has a range

  - ### headSet

    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` - when the end object cannot be compared with the elements in this set
      `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

  - ### tailSet

    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` - 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