--- jsr166/src/main/java/util/NavigableSet.java	2006/04/20 21:55:42	1.17
+++ jsr166/src/main/java/util/NavigableSet.java	2013/03/09 01:51:15	1.28
@@ -1,15 +1,15 @@
 /*
  * 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
+ * http://creativecommons.org/publicdomain/zero/1.0/
  */
 
 package java.util;
 
 /**
  * A {@link SortedSet} extended with navigation methods reporting
- * closest matches for given search targets. Methods <tt>lower},
- * {@code floor}, {@code ceiling}, and {@code higher} return elements
+ * closest matches for given search targets. Methods {@link #lower},
+ * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
  * respectively less than, less than or equal, greater than or equal,
  * and greater than a given element, returning {@code null} if there
  * is no such element.  A {@code NavigableSet} may be accessed and
@@ -18,7 +18,7 @@ package java.util;
  * 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
+ * {@link #pollFirst} and {@link #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
@@ -27,7 +27,7 @@ package java.util;
  * Subsets of any {@code NavigableSet} must implement the {@code
  * NavigableSet} interface.
  *
- * <p> The return values of navigation methods may be ambiguous in
+ * <p>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
  * {@code contains(null)}. To avoid such issues, implementations of
@@ -35,8 +35,18 @@ package java.util;
  * {@code null} elements. (Note that sorted sets of {@link
  * Comparable} elements intrinsically do not permit {@code null}.)
  *
+ * <p>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}.
+ *
  * <p>This interface is a member of the
- * <a href="{@docRoot}/../guide/collections/index.html">
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
  *
  * @author Doug Lea
@@ -125,21 +135,25 @@ 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.
+     * 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.
+     *
+     * <p>The returned set has an ordering equivalent to
+     * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}.
+     * The expression {@code s.descendingSet().descendingSet()} returns a
+     * view of {@code s} essentially equivalent to {@code s}.
      *
-     * @return a navigable set view of the mappings contained in this set,
-     *     sorted in descending order
+     * @return a reverse order view of this set
      */
     NavigableSet<E> descendingSet();
 
     /**
      * Returns an iterator over the elements in this set, in descending order.
-     * Equivalent in effect to <tt>descendingSet().iterator()</tt>.
+     * Equivalent in effect to {@code descendingSet().iterator()}.
      *
      * @return an iterator over the elements in this set, in descending order
      */
@@ -158,11 +172,11 @@ public interface NavigableSet<E> extends
      * on an attempt to insert an element outside its range.
      *
      * @param fromElement low endpoint of the returned set
-     * @param fromInclusive true if the low endpoint ({@code fromElement}) is
-     *        to be included in the returned view
+     * @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 true if the high endpoint ({@code toElement}) is
-     *        to be included in the returned view
+     * @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
      *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
      * @throws ClassCastException if {@code fromElement} and
@@ -194,8 +208,8 @@ public interface NavigableSet<E> extends
      * on an attempt to insert an element outside its range.
      *
      * @param toElement high endpoint of the returned set
-     * @param inclusive true if the high endpoint ({@code toElement}) is
-     *        to be included in the returned view
+     * @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
@@ -223,8 +237,8 @@ public interface NavigableSet<E> extends
      * on an attempt to insert an element outside its range.
      *
      * @param fromElement low endpoint of the returned set
-     * @param inclusive true if the low endpoint ({@code fromElement}) is
-     *        to be included in the returned view
+     * @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 {@code fromElement}
      * @throws ClassCastException if {@code fromElement} is not compatible
@@ -240,4 +254,37 @@ public interface NavigableSet<E> extends
      *         bounds of the range
      */
     NavigableSet<E> tailSet(E fromElement, boolean inclusive);
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
+     *
+     * @throws ClassCastException       {@inheritDoc}
+     * @throws NullPointerException     {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
+     */
+    SortedSet<E> subSet(E fromElement, E toElement);
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Equivalent to {@code headSet(toElement, false)}.
+     *
+     * @throws ClassCastException       {@inheritDoc}
+     * @throws NullPointerException     {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
+na     */
+    SortedSet<E> headSet(E toElement);
+
+    /**
+     * {@inheritDoc}
+     *
+     * <p>Equivalent to {@code tailSet(fromElement, true)}.
+     *
+     * @throws ClassCastException       {@inheritDoc}
+     * @throws NullPointerException     {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
+     */
+    SortedSet<E> tailSet(E fromElement);
 }