--- jsr166/src/main/java/util/NavigableSet.java 2005/07/20 02:18:52 1.12 +++ jsr166/src/main/java/util/NavigableSet.java 2012/11/18 18:03:10 1.26 @@ -1,57 +1,67 @@ /* - * 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 + * Written by Doug Lea and Josh Bloch 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 java.util; -import java.util.*; // for javadoc (till 6280605 is fixed) /** * A {@link SortedSet} extended with navigation methods reporting - * closest matches for given search targets. Methods lower, - * floor, ceiling, and higher return elements + * closest matches for given search targets. Methods {@code lower}, + * {@code floor}, {@code ceiling}, and {@code 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. + * and greater than a given element, returning {@code null} if there + * is no such element. A {@code NavigableSet} may be accessed and + * traversed in either ascending or descending order. The {@code + * descendingSet} method returns a view of the set with the senses of + * all relational and directional methods inverted. The performance of + * ascending operations and views is likely to be faster than that of + * descending ones. This interface additionally defines methods + * {@code pollFirst} and {@code pollLast} that return and remove the + * lowest and highest element, if one exists, else returning {@code + * null}. Methods {@code subSet}, {@code headSet}, + * and {@code tailSet} differ from the like-named {@code + * SortedSet} methods in accepting additional arguments describing + * whether lower and upper bounds are inclusive versus exclusive. + * Subsets of any {@code NavigableSet} must implement the {@code + * NavigableSet} interface. * - *

The return values of navigation methods may be ambiguous in - * implementations that permit null elements. However, even + *

The return values of navigation methods may be ambiguous in + * implementations that permit {@code null} elements. However, even * in this case the result can be disambiguated by checking - * contains(null). To avoid such issues, implementations of + * {@code 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.) + * {@code null} elements. (Note that sorted sets of {@link + * Comparable} elements intrinsically do not permit {@code null}.) + * + *

Methods + * {@link #subSet(Object, Object) subSet(E, E)}, + * {@link #headSet(Object) headSet(E)}, and + * {@link #tailSet(Object) tailSet(E)} + * are specified to return {@code SortedSet} to allow existing + * implementations of {@code SortedSet} to be compatibly retrofitted to + * implement {@code NavigableSet}, but extensions and implementations + * of this interface are encouraged to override these methods to return + * {@code NavigableSet}. * *

This interface is a member of the - * + * * Java Collections Framework. * * @author Doug Lea + * @author Josh Bloch * @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. + * given element, or {@code 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 + * @return the greatest element less than {@code e}, + * or {@code 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 @@ -61,11 +71,11 @@ public interface NavigableSet extends /** * Returns the greatest element in this set less than or equal to - * the given element, or null if there is no such element. + * the given element, or {@code 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 + * @return the greatest element less than or equal to {@code e}, + * or {@code 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 @@ -75,11 +85,11 @@ public interface NavigableSet extends /** * Returns the least element in this set greater than or equal to - * the given element, or null if there is no such element. + * the given element, or {@code 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 + * @return the least element greater than or equal to {@code e}, + * or {@code 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 @@ -89,11 +99,11 @@ public interface NavigableSet extends /** * Returns the least element in this set strictly greater than the - * given element, or null if there is no such element. + * given element, or {@code 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 + * @return the least element greater than {@code e}, + * or {@code 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 @@ -102,16 +112,18 @@ public interface NavigableSet extends E higher(E e); /** - * Retrieves and removes the first (lowest) element. + * Retrieves and removes the first (lowest) element, + * or returns {@code null} if this set is empty. * - * @return the first element, or null if this set is empty + * @return the first element, or {@code null} if this set is empty */ E pollFirst(); /** - * Retrieves and removes the last (highest) element. + * Retrieves and removes the last (highest) element, + * or returns {@code null} if this set is empty. * - * @return the last element, or null if this set is empty + * @return the last element, or {@code null} if this set is empty */ E pollLast(); @@ -123,96 +135,156 @@ public interface NavigableSet extends Iterator iterator(); /** + * Returns a reverse order view of the elements contained in this set. + * The descending set is backed by this set, so changes to the set are + * reflected in the descending set, and vice-versa. If either set is + * modified while an iteration over either set is in progress (except + * through the iterator's own {@code remove} operation), the results of + * the iteration are undefined. + * + *

The returned set has an ordering equivalent to + * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator()). + * The expression {@code s.descendingSet().descendingSet()} returns a + * view of {@code s} essentially equivalent to {@code s}. + * + * @return a reverse order view of this set + */ + NavigableSet descendingSet(); + + /** * Returns an iterator over the elements in this set, in descending order. + * Equivalent in effect to {@code descendingSet().iterator()}. * * @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. + * Returns a view of the portion of this set whose elements range from + * {@code fromElement} to {@code toElement}. If {@code fromElement} and + * {@code toElement} are equal, the returned set is empty unless {@code + * fromExclusive} and {@code toExclusive} are both true. 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 + *

The returned set will throw an {@code 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 + * @param fromElement low endpoint of the returned set + * @param fromInclusive {@code true} if the low endpoint + * is to be included in the returned view + * @param toElement high endpoint of the returned set + * @param toInclusive {@code true} if the high endpoint + * is to be included in the returned view * @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 + * {@code fromElement}, inclusive, to {@code toElement}, exclusive + * @throws ClassCastException if {@code fromElement} and + * {@code 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 + * to, throw this exception if {@code fromElement} or + * {@code toElement} cannot be compared to elements currently in * the set. - * @throws NullPointerException if fromElement or - * toElement is null and this set does + * @throws NullPointerException if {@code fromElement} or + * {@code 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); + * @throws IllegalArgumentException if {@code fromElement} is + * greater than {@code toElement}; or if this set itself + * has a restricted range, and {@code fromElement} or + * {@code toElement} lies outside the bounds of the range. + */ + NavigableSet subSet(E fromElement, boolean fromInclusive, + E toElement, boolean toInclusive); /** - * 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. + * Returns a view of the portion of this set whose elements are less than + * (or equal to, if {@code inclusive} is true) {@code 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 + *

The returned set will throw an {@code 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 + * @param toElement high endpoint of the returned set + * @param inclusive {@code true} if the high endpoint + * is to be included in the returned view + * @return a view of the portion of this set whose elements are less than + * (or equal to, if {@code inclusive} is true) {@code toElement} + * @throws ClassCastException if {@code toElement} is not compatible * with this set's comparator (or, if the set has no comparator, - * if toElement does not implement {@link Comparable}). + * if {@code toElement} does not implement {@link Comparable}). * Implementations may, but are not required to, throw this - * exception if toElement cannot be compared to elements + * exception if {@code toElement} cannot be compared to elements * currently in the set. - * @throws NullPointerException if toElement is null and + * @throws NullPointerException if {@code 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 + * restricted range, and {@code toElement} lies outside the * bounds of the range */ - NavigableSet navigableHeadSet(E toElement); + NavigableSet headSet(E toElement, boolean inclusive); /** - * 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. + * Returns a view of the portion of this set whose elements are greater + * than (or equal to, if {@code inclusive} is true) {@code 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 + *

The returned set will throw an {@code IllegalArgumentException} * on an attempt to insert an element outside its range. * - * @param fromElement low endpoint (inclusive) of the returned set + * @param fromElement low endpoint of the returned set + * @param inclusive {@code true} if the low endpoint + * is to be included in the returned view * @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 + * than or equal to {@code fromElement} + * @throws ClassCastException if {@code fromElement} is not compatible * with this set's comparator (or, if the set has no comparator, - * if fromElement does not implement {@link Comparable}). + * if {@code fromElement} does not implement {@link Comparable}). * Implementations may, but are not required to, throw this - * exception if fromElement cannot be compared to elements + * exception if {@code fromElement} cannot be compared to elements * currently in the set. - * @throws NullPointerException if fromElement is null + * @throws NullPointerException if {@code 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 + * restricted range, and {@code fromElement} lies outside the * bounds of the range */ - NavigableSet navigableTailSet(E fromElement); + NavigableSet tailSet(E fromElement, boolean inclusive); + + /** + * {@inheritDoc} + * + *

Equivalent to {@code subSet(fromElement, true, toElement, false)}. + * + * @throws ClassCastException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + */ + SortedSet subSet(E fromElement, E toElement); + + /** + * {@inheritDoc} + * + *

Equivalent to {@code headSet(toElement, false)}. + * + * @throws ClassCastException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} +na */ + SortedSet headSet(E toElement); + + /** + * {@inheritDoc} + * + *

Equivalent to {@code tailSet(fromElement, true)}. + * + * @throws ClassCastException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + */ + SortedSet tailSet(E fromElement); }