ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/NavigableSet.java
(Generate patch)

Comparing jsr166/src/main/java/util/NavigableSet.java (file contents):
Revision 1.18 by jsr166, Fri Apr 21 02:53:25 2006 UTC vs.
Revision 1.26 by jsr166, Sun Nov 18 18:03:10 2012 UTC

# Line 1 | Line 1
1   /*
2   * Written by Doug Lea and Josh Bloch with assistance from members of JCP
3   * JSR-166 Expert Group and released to the public domain, as explained at
4 < * http://creativecommons.org/licenses/publicdomain
4 > * http://creativecommons.org/publicdomain/zero/1.0/
5   */
6  
7   package java.util;
# Line 27 | Line 27 | package java.util;
27   * Subsets of any {@code NavigableSet} must implement the {@code
28   * NavigableSet} interface.
29   *
30 < * <p> The return values of navigation methods may be ambiguous in
30 > * <p>The return values of navigation methods may be ambiguous in
31   * implementations that permit {@code null} elements. However, even
32   * in this case the result can be disambiguated by checking
33   * {@code contains(null)}. To avoid such issues, implementations of
# Line 35 | Line 35 | package java.util;
35   * {@code null} elements. (Note that sorted sets of {@link
36   * Comparable} elements intrinsically do not permit {@code null}.)
37   *
38 + * <p>Methods
39 + * {@link #subSet(Object, Object) subSet(E, E)},
40 + * {@link #headSet(Object) headSet(E)}, and
41 + * {@link #tailSet(Object) tailSet(E)}
42 + * are specified to return {@code SortedSet} to allow existing
43 + * implementations of {@code SortedSet} to be compatibly retrofitted to
44 + * implement {@code NavigableSet}, but extensions and implementations
45 + * of this interface are encouraged to override these methods to return
46 + * {@code NavigableSet}.
47 + *
48   * <p>This interface is a member of the
49 < * <a href="{@docRoot}/../guide/collections/index.html">
49 > * <a href="{@docRoot}/../technotes/guides/collections/index.html">
50   * Java Collections Framework</a>.
51   *
52   * @author Doug Lea
# Line 125 | Line 135 | public interface NavigableSet<E> extends
135      Iterator<E> iterator();
136  
137      /**
138 <     * Returns a {@link NavigableSet} view of the elements contained in this
139 <     * set in descending order.  The descending set is backed by this set, so
140 <     * changes to the set are reflected in the descending set, and vice-versa.
141 <     * If either set is modified while an iteration over the other set is in
142 <     * in progress (except through the iterator's own {@code remove} operation),
143 <     * the results of the iteration are undefined.
138 >     * Returns a reverse order view of the elements contained in this set.
139 >     * The descending set is backed by this set, so changes to the set are
140 >     * reflected in the descending set, and vice-versa.  If either set is
141 >     * modified while an iteration over either set is in progress (except
142 >     * through the iterator's own {@code remove} operation), the results of
143 >     * the iteration are undefined.
144 >     *
145 >     * <p>The returned set has an ordering equivalent to
146 >     * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
147 >     * The expression {@code s.descendingSet().descendingSet()} returns a
148 >     * view of {@code s} essentially equivalent to {@code s}.
149       *
150 <     * @return a navigable set view of the mappings contained in this set,
136 <     *     sorted in descending order
150 >     * @return a reverse order view of this set
151       */
152      NavigableSet<E> descendingSet();
153  
154      /**
155       * Returns an iterator over the elements in this set, in descending order.
156 <     * Equivalent in effect to <tt>descendingSet().iterator()</tt>.
156 >     * Equivalent in effect to {@code descendingSet().iterator()}.
157       *
158       * @return an iterator over the elements in this set, in descending order
159       */
# Line 158 | Line 172 | public interface NavigableSet<E> extends
172       * on an attempt to insert an element outside its range.
173       *
174       * @param fromElement low endpoint of the returned set
175 <     * @param fromInclusive true if the low endpoint ({@code fromElement}) is
176 <     *        to be included in the returned view
175 >     * @param fromInclusive {@code true} if the low endpoint
176 >     *        is to be included in the returned view
177       * @param toElement high endpoint of the returned set
178 <     * @param toInclusive true if the high endpoint ({@code toElement}) is
179 <     *        to be included in the returned view
178 >     * @param toInclusive {@code true} if the high endpoint
179 >     *        is to be included in the returned view
180       * @return a view of the portion of this set whose elements range from
181       *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
182       * @throws ClassCastException if {@code fromElement} and
# Line 194 | Line 208 | public interface NavigableSet<E> extends
208       * on an attempt to insert an element outside its range.
209       *
210       * @param toElement high endpoint of the returned set
211 <     * @param inclusive true if the high endpoint ({@code toElement}) is
212 <     *        to be included in the returned view
211 >     * @param inclusive {@code true} if the high endpoint
212 >     *        is to be included in the returned view
213       * @return a view of the portion of this set whose elements are less than
214       *         (or equal to, if {@code inclusive} is true) {@code toElement}
215       * @throws ClassCastException if {@code toElement} is not compatible
# Line 223 | Line 237 | public interface NavigableSet<E> extends
237       * on an attempt to insert an element outside its range.
238       *
239       * @param fromElement low endpoint of the returned set
240 <     * @param inclusive true if the low endpoint ({@code fromElement}) is
241 <     *        to be included in the returned view
240 >     * @param inclusive {@code true} if the low endpoint
241 >     *        is to be included in the returned view
242       * @return a view of the portion of this set whose elements are greater
243       *         than or equal to {@code fromElement}
244       * @throws ClassCastException if {@code fromElement} is not compatible
# Line 240 | Line 254 | public interface NavigableSet<E> extends
254       *         bounds of the range
255       */
256      NavigableSet<E> tailSet(E fromElement, boolean inclusive);
257 +
258 +    /**
259 +     * {@inheritDoc}
260 +     *
261 +     * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
262 +     *
263 +     * @throws ClassCastException       {@inheritDoc}
264 +     * @throws NullPointerException     {@inheritDoc}
265 +     * @throws IllegalArgumentException {@inheritDoc}
266 +     */
267 +    SortedSet<E> subSet(E fromElement, E toElement);
268 +
269 +    /**
270 +     * {@inheritDoc}
271 +     *
272 +     * <p>Equivalent to {@code headSet(toElement, false)}.
273 +     *
274 +     * @throws ClassCastException       {@inheritDoc}
275 +     * @throws NullPointerException     {@inheritDoc}
276 +     * @throws IllegalArgumentException {@inheritDoc}
277 + na     */
278 +    SortedSet<E> headSet(E toElement);
279 +
280 +    /**
281 +     * {@inheritDoc}
282 +     *
283 +     * <p>Equivalent to {@code tailSet(fromElement, true)}.
284 +     *
285 +     * @throws ClassCastException       {@inheritDoc}
286 +     * @throws NullPointerException     {@inheritDoc}
287 +     * @throws IllegalArgumentException {@inheritDoc}
288 +     */
289 +    SortedSet<E> tailSet(E fromElement);
290   }

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines