--- jsr166/src/main/java/util/NavigableSet.java	2006/02/07 20:54:24	1.14
+++ jsr166/src/main/java/util/NavigableSet.java	2006/04/19 15:07:14	1.15
@@ -1,6 +1,6 @@
 /*
- * Written by Doug Lea with assistance from members of JCP JSR-166
- * Expert Group and released to the public domain, as explained at
+ * 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/licenses/publicdomain
  */
 
@@ -8,49 +8,50 @@ package java.util;
 
 /**
  * A {@link SortedSet} extended with navigation methods reporting
- * closest matches for given search targets. Methods <tt>lower</tt>,
- * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return elements
+ * closest matches for given search targets. Methods <tt>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 <tt>null</tt> if there is
- * no such element.  A <tt>NavigableSet</tt> may be viewed and traversed
- * in either ascending or descending order.  The <tt>Collection</tt>
- * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
- * the additional method <tt>descendingIterator</tt> returns a
- * descending iterator. The performance of ascending traversals is
- * likely to be faster than descending traversals.  This interface
- * additionally defines methods <tt>pollFirst</tt> and
- * <tt>pollLast</tt> that return and remove the lowest and highest
- * element, if one exists, else returning <tt>null</tt>.
- * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
- * <tt>navigableTailSet</tt> differ from the similarly named
- * <tt>SortedSet</tt> methods only in their declared return types.
- * Subsets of any <tt>NavigableSet</tt> must implement the
- * <tt>NavigableSet</tt> 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 navigableSubSet}, {@code navigableHeadSet},
+ * and {@code navigableTailSet} differ from the similarly 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.
  *
  * <p> The return values of navigation methods may be ambiguous in
- * implementations that permit <tt>null</tt> elements. However, even
+ * implementations that permit {@code null} elements. However, even
  * in this case the result can be disambiguated by checking
- * <tt>contains(null)</tt>. To avoid such issues, implementations of
+ * {@code contains(null)}. To avoid such issues, implementations of
  * this interface are encouraged to <em>not</em> permit insertion of
- * <tt>null</tt> elements. (Note that sorted sets of {@link
- * Comparable} elements intrinsically do not permit <tt>null</tt>.)
+ * {@code null} elements. (Note that sorted sets of {@link
+ * Comparable} elements intrinsically do not permit {@code null}.)
  *
  * <p>This interface is a member of the
  * <a href="{@docRoot}/../guide/collections/index.html">
  * Java Collections Framework</a>.
  *
  * @author Doug Lea
+ * @author Josh Bloch
  * @param <E> the type of elements maintained by this set
  * @since 1.6
  */
 public interface NavigableSet<E> extends SortedSet<E> {
     /**
      * Returns the greatest element in this set strictly less than the
-     * given element, or <tt>null</tt> 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 <tt>e</tt>,
-     *         or <tt>null</tt> 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
@@ -60,11 +61,11 @@ public interface NavigableSet<E> extends
 
     /**
      * Returns the greatest element in this set less than or equal to
-     * the given element, or <tt>null</tt> 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 <tt>e</tt>,
-     *         or <tt>null</tt> 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
@@ -74,11 +75,11 @@ public interface NavigableSet<E> extends
 
     /**
      * Returns the least element in this set greater than or equal to
-     * the given element, or <tt>null</tt> 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 <tt>e</tt>,
-     *         or <tt>null</tt> 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
@@ -88,11 +89,11 @@ public interface NavigableSet<E> extends
 
     /**
      * Returns the least element in this set strictly greater than the
-     * given element, or <tt>null</tt> 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 <tt>e</tt>,
-     *         or <tt>null</tt> 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,17 +103,17 @@ public interface NavigableSet<E> extends
 
     /**
      * Retrieves and removes the first (lowest) element,
-     * or returns <tt>null</tt> if this set is empty.
+     * or returns {@code null} if this set is empty.
      *
-     * @return the first element, or <tt>null</tt> 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,
-     * or returns <tt>null</tt> if this set is empty.
+     * or returns {@code null} if this set is empty.
      *
-     * @return the last element, or <tt>null</tt> if this set is empty
+     * @return the last element, or {@code null} if this set is empty
      */
     E pollLast();
 
@@ -124,96 +125,119 @@ public interface NavigableSet<E> extends
     Iterator<E> iterator();
 
     /**
+     * Returns a {@link NavigableSet} view of the elements contained in this
+     * set in descending order.  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 the other set is in
+     * in progress (except through the iterator's own {@code remove} operation),
+     * the results of the iteration are undefined.
+     *
+     * @return a navigable set view of the mappings contained in this set,
+     *     sorted in descending order
+     */
+    NavigableSet<E> descendingSet();
+
+    /**
      * Returns an iterator over the elements in this set, in descending order.
+     * Equivalent in effect to <tt>descendingSet().iterator()</tt>.
      *
      * @return an iterator over the elements in this set, in descending order
      */
     Iterator<E> descendingIterator();
 
     /**
-     * Returns a view of the portion of this set whose elements range
-     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
-     * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> 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.
      *
-     * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
+     * <p>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 true if the low endpoint ({@code fromElement}) is
+     *        to be included in the the returned view
+     * @param toElement high endpoint of the returned set
+     * @param toInclusive true if the high endpoint ({@code toElement}) is
+     *        to be included in the the returned view
      * @return a view of the portion of this set whose elements range from
-     *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive
-     * @throws ClassCastException if <tt>fromElement</tt> and
-     *         <tt>toElement</tt> 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 <tt>fromElement</tt> or
-     *         <tt>toElement</tt> 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 <tt>fromElement</tt> or
-     *         <tt>toElement</tt> 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 <tt>fromElement</tt> is
-     *         greater than <tt>toElement</tt>; or if this set itself
-     *         has a restricted range, and <tt>fromElement</tt> or
-     *         <tt>toElement</tt> lies outside the bounds of the range.
-     */
-    NavigableSet<E> 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<E> navigableSubSet(E fromElement, boolean fromInclusive,
+                                    E toElement,   boolean toInclusive);
 
     /**
-     * Returns a view of the portion of this set whose elements are
-     * strictly less than <tt>toElement</tt>.  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.
      *
-     * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
+     * <p>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 <tt>toElement</tt>
-     * @throws ClassCastException if <tt>toElement</tt> is not compatible
+     * @param toElement high endpoint of the returned set
+     * @param inclusive true if the high endpoint ({@code toElement}) is
+     *        to be included in the 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 <tt>toElement</tt> does not implement {@link Comparable}).
+     *         if {@code toElement} does not implement {@link Comparable}).
      *         Implementations may, but are not required to, throw this
-     *         exception if <tt>toElement</tt> cannot be compared to elements
+     *         exception if {@code toElement} cannot be compared to elements
      *         currently in the set.
-     * @throws NullPointerException if <tt>toElement</tt> 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 <tt>toElement</tt> lies outside the
+     *         restricted range, and {@code toElement} lies outside the
      *         bounds of the range
      */
-    NavigableSet<E> navigableHeadSet(E toElement);
+    NavigableSet<E> navigableHeadSet(E toElement, boolean inclusive);
 
     /**
-     * Returns a view of the portion of this set whose elements are
-     * greater than or equal to <tt>fromElement</tt>.  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.
      *
-     * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
+     * <p>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 true if the low endpoint ({@code fromElement}) is
+     *        to be included in the the returned view
      * @return a view of the portion of this set whose elements are greater
-     *         than or equal to <tt>fromElement</tt>
-     * @throws ClassCastException if <tt>fromElement</tt> 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 <tt>fromElement</tt> does not implement {@link Comparable}).
+     *         if {@code fromElement} does not implement {@link Comparable}).
      *         Implementations may, but are not required to, throw this
-     *         exception if <tt>fromElement</tt> cannot be compared to elements
+     *         exception if {@code fromElement} cannot be compared to elements
      *         currently in the set.
-     * @throws NullPointerException if <tt>fromElement</tt> 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 <tt>fromElement</tt> lies outside the
+     *         restricted range, and {@code fromElement} lies outside the
      *         bounds of the range
      */
-    NavigableSet<E> navigableTailSet(E fromElement);
+    NavigableSet<E> navigableTailSet(E fromElement, boolean inclusive);
 }