/*
* Written by Doug Lea with assistance from members of JCP JSR-166
* Expert Group and released to the public domain, as explained at
* http://creativecommons.org/licenses/publicdomain
*/
package java.util;
/**
* A {@link SortedSet} extended with navigation methods reporting
* closest matches for given search targets. Methods lower,
* floor, ceiling, and higher return elements
* respectively less than, less than or equal, greater than or equal,
* and greater than a given element, returning null if there is
* no such element. A NavigableSet may be viewed and traversed
* in either ascending or descending order. The Collection
* iterator method returns an ascending Iterator and
* the additional method descendingIterator returns a
* descending iterator. The performance of ascending traversals is
* likely to be faster than descending traversals. This interface
* additionally defines methods pollFirst and
* pollLast that return and remove the lowest and highest
* element, if one exists, else returning null.
* Methods navigableSubSet, navigableHeadSet, and
* navigableTailSet differ from the similarly named
* SortedSet methods only in their declared return types.
* Subsets of any NavigableSet must implement the
* NavigableSet interface.
*
* 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 to not permit insertion of
* null elements. (Note that sorted sets of {@link
* Comparable} elements intrinsically do not permit null.)
*
*
This interface is a member of the
*
* Java Collections Framework.
*
* @author Doug Lea
* @param the type of elements maintained by this set
* @since 1.6
*/
public interface NavigableSet extends SortedSet {
/**
* Returns the greatest element in this set 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 e,
* or null if there is no such element
* @throws ClassCastException if the specified element cannot be
* compared with the elements currently in the set
* @throws NullPointerException if the specified element is null
* and this set does not permit null elements
*/
E lower(E e);
/**
* Returns the greatest element in this set 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 e,
* or null if there is no such element
* @throws ClassCastException if the specified element cannot be
* compared with the elements currently in the set
* @throws NullPointerException if the specified element is null
* and this set does not permit null elements
*/
E floor(E e);
/**
* Returns the least element in this set greater than or equal to
* the given element, or null if there is no such element.
*
* @param e the value to match
* @return the least element greater than or equal to e,
* or null if there is no such element
* @throws ClassCastException if the specified element cannot be
* compared with the elements currently in the set
* @throws NullPointerException if the specified element is null
* and this set does not permit null elements
*/
E ceiling(E e);
/**
* Returns the least element in this set 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 e,
* or null if there is no such element
* @throws ClassCastException if the specified element cannot be
* compared with the elements currently in the set
* @throws NullPointerException if the specified element is null
* and this set does not permit null elements
*/
E higher(E e);
/**
* Retrieves and removes the first (lowest) element,
* or returns null if this set is empty.
*
* @return the first element, or null if this set is empty
*/
E pollFirst();
/**
* Retrieves and removes the last (highest) element,
* or returns null if this set is empty.
*
* @return the last element, or null if this set is empty
*/
E pollLast();
/**
* Returns an iterator over the elements in this set, in ascending order.
*
* @return an iterator over the elements in this set, in ascending order
*/
Iterator iterator();
/**
* Returns an iterator over the elements in this set, in descending order.
*
* @return an iterator over the elements in this set, in descending order
*/
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 set is empty.) The returned set is backed
* by this set, so changes in the returned set are reflected in
* this set, and vice-versa. The returned set supports all
* optional set operations that this set supports.
*
* The returned set will throw an IllegalArgumentException
* on an attempt to insert an element outside its range.
*
* @param fromElement low endpoint (inclusive) of the returned set
* @param toElement high endpoint (exclusive) of the returned set
* @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). Implementations may, but are not required
* to, throw this exception if fromElement or
* toElement cannot be compared to elements currently in
* the set.
* @throws NullPointerException if fromElement or
* toElement is null and this set does
* not permit null elements
* @throws IllegalArgumentException if fromElement is
* greater than toElement; or if this set itself
* has a restricted range, and fromElement or
* toElement lies outside the bounds of the range.
*/
NavigableSet navigableSubSet(E fromElement, E toElement);
/**
* Returns a view of the portion of this set whose elements are
* strictly less than toElement. The returned set is
* backed by this set, so changes in the returned set are
* reflected in this set, and vice-versa. The returned set
* supports all optional set operations that this set supports.
*
* The returned set will throw an IllegalArgumentException
* on an attempt to insert an element outside its range.
*
* @param toElement high endpoint (exclusive) of the returned set
* @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 {@link Comparable}).
* Implementations may, but are not required to, throw this
* exception if toElement cannot be compared to elements
* currently in the set.
* @throws NullPointerException if toElement is null and
* this set does not permit null elements
* @throws IllegalArgumentException if this set itself has a
* restricted range, and toElement lies outside the
* bounds of the range
*/
NavigableSet navigableHeadSet(E toElement);
/**
* Returns a view of the portion of this set whose elements are
* greater than or equal to fromElement. The returned
* set is backed by this set, so changes in the returned set are
* reflected in this set, and vice-versa. The returned set
* supports all optional set operations that this set supports.
*
* The returned set will throw an IllegalArgumentException
* on an attempt to insert an element outside its range.
*
* @param fromElement low endpoint (inclusive) of the returned set
* @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 {@link Comparable}).
* Implementations may, but are not required to, throw this
* exception if fromElement cannot be compared to elements
* currently in the set.
* @throws NullPointerException if fromElement is null
* and this set does not permit null elements
* @throws IllegalArgumentException if this set itself has a
* restricted range, and fromElement lies outside the
* bounds of the range
*/
NavigableSet navigableTailSet(E fromElement);
}