The return values of navigation methods may be ambiguous in
* implementations that permit `null` elements. However, even
* in this case the result can be disambiguated by checking
* `contains(null)`. To avoid such issues, implementations of
* this interface are encouraged *not* to permit insertion of
* `null` elements. (Note that sorted sets of {@link
* Comparable} elements intrinsically do not permit `null`.)
*
* @author Doug Lea
* @param `null` if there is no such element.
*
* @param e the value to match
* @return an element greater than or equal to given element, or
* `null` if there is no such element.
* @throws ClassCastException if e cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if e is `null`
* and this set does not permit `null` elements
*/
E ceiling(E e);
/**
* Returns an element strictly less than the given element, or
* `null` if there is no such element.
*
* @param e the value to match
* @return the greatest element less than the given element, or
* `null` if there is no such element.
* @throws ClassCastException if e cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if e is `null`
* and this set does not permit `null` elements
*/
E lower(E e);
/**
* Returns an element less than or equal to the given element, or
* `null` if there is no such element.
*
* @param e the value to match
* @return the greatest element less than or equal to given
* element, or `null` if there is no such element.
* @throws ClassCastException if e cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if e is `null`.
* and this set does not permit `null` elements
*/
E floor(E e);
/**
* Returns an element strictly greater than the given element, or
* `null` if there is no such element.
*
* @param e the value to match
* @return the least element greater than the given element, or
* `null` if there is no such element.
* @throws ClassCastException if e cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if e is `null`
* and this set does not permit `null` elements
*/
E higher(E e);
/**
* Retrieves and removes the first (lowest) element.
*
* @return the first element, or `null` if empty.
*/
E pollFirst();
/**
* Retrieves and removes the last (highest) element.
*
* @return the last element, or `null` if empty.
*/
E pollLast();
/**
* Returns an iterator over the elements in this collection, in
* descending order.
*
* @return an `Iterator` over the elements in this collection
*/
Iterator`fromElement`, inclusive, to `toElement`,
* exclusive. (If `fromElement` and `toElement` are
* equal, the returned navigable set is empty.) The returned
* navigable set is backed by this set, so changes in the returned
* navigable set are reflected in this set, and vice-versa.
*
* @param fromElement low endpoint (inclusive) of the subSet.
* @param toElement high endpoint (exclusive) of the subSet.
* @return a view of the portion of this set whose elements range from
* `fromElement`, inclusive, to `toElement`,
* exclusive.
* @throws ClassCastException if `fromElement` and
* `toElement` cannot be compared to one another using
* this set's comparator (or, if the set has no comparator,
* using natural ordering).
* @throws IllegalArgumentException if `fromElement` is
* greater than `toElement`.
* @throws NullPointerException if `fromElement` or
* `toElement` is `null`
* and this set does not permit `null` elements
*/
NavigableSet`toElement`. The returned navigable
* set is backed by this set, so changes in the returned navigable
* set are reflected in this set, and vice-versa.
* @param toElement high endpoint (exclusive) of the headSet.
* @return a view of the portion of this set whose elements are strictly
* less than toElement.
* @throws ClassCastException if `toElement` is not compatible
* with this set's comparator (or, if the set has no comparator,
* if `toElement` does not implement `Comparable`).
* @throws NullPointerException if `toElement` is `null`
* and this set does not permit `null` elements
*/
NavigableSet`fromElement`. The returned
* navigable set is backed by this set, so changes in the returned
* navigable set are reflected in this set, and vice-versa.
* @param fromElement low endpoint (inclusive) of the tailSet.
* @return a view of the portion of this set whose elements are
* greater than or equal to `fromElement`.
* @throws ClassCastException if `fromElement` is not
* compatible with this set's comparator (or, if the set has no
* comparator, if `fromElement` does not implement
* `Comparable`).
* @throws NullPointerException if `fromElement` is `null`
* and this set does not permit `null` elements
*/
NavigableSet