jsr166x.NavigableSet Maven / Gradle / Ivy
/*
* 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/publicdomain/zero/1.0/
*/
package jsr166x;
import java.util.*;
/**
* A {@link SortedSet} extended with navigation methods reporting
* closest matches for given search targets. Methods lower,
* floor, ceiling, and higher return keys
* respectively less than, less than or equal, greater than or equal,
* and greater than a given key, returning null if there is
* no such key. 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
* 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 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 deas not permit null elements
*/
public 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 deas not permit null elements
*/
public 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 deas not permit null elements
*/
public 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 deas not permit null elements
*/
public E higher(E o);
/**
* Retrieves and removes the first (lowest) element.
*
* @return the first element, or null if empty.
*/
public E pollFirst();
/**
* Retrieves and removes the last (highest) element.
*
* @return the last element, or null if empty.
*/
public 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
* sorted set is empty.) The returned sorted set is backed by this set,
* so changes in the returned sorted 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 deas not permit null elements
*/
public NavigableSet subSet(E fromElement, E toElement);
/**
* Returns a view of the portion of this set whose elements are strictly
* less than toElement. The returned sorted set is backed by
* this set, so changes in the returned sorted 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 deas not permit null elements
*/
public NavigableSet headSet(E toElement);
/**
* Returns a view of the portion of this set whose elements are
* greater than or equal to fromElement. The returned
* sorted set is backed by this set, so changes in the returned
* sorted 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 deas not permit null elements
*/
public NavigableSet tailSet(E fromElement);
}