pollLast that return and remove the lowest and highest key,
* if one exists, else returning null.
*
* 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 the type of elements maintained by this set
*/
public interface NavigableSet extends SortedSet {
/**
* Returns an element greater than or equal to the given element, or
* null if there is no such element.
*
* @param o 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 o cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if o is null
* and this set does not permit null elements
*/
E ceiling(E o);
/**
* Returns an element strictly less than the given element, or
* null if there is no such element.
*
* @param o the value to match
* @return the greatest element less than the given element, or
* null if there is no such element.
* @throws ClassCastException if o cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if o is null
* and this set does not permit null elements
*/
E lower(E o);
/**
* Returns an element less than or equal to the given element, or
* null if there is no such element.
*
* @param o 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 o cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if o is null.
* and this set does not permit null elements
*/
E floor(E o);
/**
* Returns an element strictly greater than the given element, or
* null if there is no such element.
*
* @param o the value to match
* @return the least element greater than the given element, or
* null if there is no such element.
* @throws ClassCastException if o cannot be compared with the elements
* currently in the set.
* @throws NullPointerException if o is null
* and this set does not permit null elements
*/
E higher(E o);
/**
* 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 descendingIterator();
/**
* Returns a view of the portion of this set whose elements range
* from 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. Note:
* This method differs from SortedSet.subSet only in that
* the returned set is guaranteed to support the
* NavigableSet interface.
*
* @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 navigableSubSet(E fromElement, E toElement);
/**
* Returns a view of the portion of this set whose elements are
* strictly less than 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 navigableHeadSet(E toElement);
/**
* Returns a view of the portion of this set whose elements are
* greater than or equal to 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 navigableTailSet(E fromElement);
}