--- jsr166/src/main/java/util/NavigableSet.java 2005/05/03 02:52:07 1.8 +++ jsr166/src/main/java/util/NavigableSet.java 2005/05/16 06:27:52 1.9 @@ -9,18 +9,18 @@ package java.util; /** * A {@link SortedSet} extended with navigation methods reporting * closest matches for given search targets. Methods lower, - * floor, ceiling, and higher return keys + * floor, ceiling, and higher return elements * 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 + * 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 + * 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 key, - * if one exists, else returning null. + * 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 that the returned sets @@ -30,7 +30,7 @@ package java.util; * 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 + * this interface are encouraged to not permit insertion of * null elements. (Note that sorted sets of {@link * Comparable} elements intrinsically do not permit null.) * @@ -44,80 +44,80 @@ package java.util; */ public interface NavigableSet extends SortedSet { /** - * Returns an element greater than or equal to the given element, or - * null if there is no such element. + * 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 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 + * @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 ceiling(E e); + E lower(E e); /** - * Returns an element strictly less than the given element, or - * null if there is no such element. + * 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 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 + * @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 lower(E e); + E floor(E e); /** - * Returns an element less than or equal to the given element, or - * null if there is no such element. + * 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 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 + * @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 floor(E e); + E ceiling(E e); /** - * Returns an element strictly greater than the given element, or - * null if there is no such element. + * 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 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 + * @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. * - * @return the first element, or null if empty. + * @return the first element, or null if this set is empty */ E pollFirst(); /** * Retrieves and removes the last (highest) element. * - * @return the last element, or null if empty. + * @return the last element, or null if this set is empty */ E pollLast(); /** - * Returns an iterator over the elements in this collection, in + * Returns an iterator over the elements in this set, in * descending order. * - * @return an Iterator over the elements in this collection + * @return an Iterator over the elements in this set */ Iterator descendingIterator(); @@ -125,57 +125,86 @@ public interface NavigableSet extends * 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. + * 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. * - * @param fromElement low endpoint (inclusive) of the subSet. - * @param toElement high endpoint (exclusive) of the subSet. + *

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. + * 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. + * 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 + * 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 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. + * 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. + * 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 + * 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 - * 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 + * 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); }