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

Comparing jsr166/src/jsr166x/NavigableSet.java (file contents):
Revision 1.1 by dl, Mon Sep 6 17:01:54 2004 UTC vs.
Revision 1.2 by dl, Tue Sep 7 11:37:57 2004 UTC

# Line 8 | Line 8 | package jsr166x;
8   import java.util.*;
9  
10   /**
11 < * A {@link SortedSet} extended with methods reporting closest matches
12 < * for given search targets. Methods <tt>lower</tt>, <tt>floor</tt>,
13 < * <tt>ceiling</tt>, and <tt>higher</tt> return keys respectively
14 < * less, less than or equal, greater than or equal, and greater than a
15 < * given key, returning <tt>null</tt> if there is no such key.  These
16 < * methods are designed for locating, not traversing entries. To
17 < * traverse, use view iterators and/or <tt>subset</tt>. This interface
18 < * additionally defines methods <tt>pollFirst</tt> and
19 < * <t>pollLast</tt> that return and remove the lowest and highest key,
20 < * if one exists, else returning <tt>null</tt>.
11 > * A {@link SortedSet} extended with navigation methods reporting
12 > * closest matches for given search targets. Methods <tt>lower</tt>,
13 > * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys
14 > * respectively less than, less than or equal, greater than or equal,
15 > * and greater than a given key, returning <tt>null</tt> if there is
16 > * no such key.  These methods are designed for locating, not
17 > * traversing entries. To traverse, use view iterators and/or
18 > * <tt>subset</tt>. This interface additionally defines methods
19 > * <tt>pollFirst</tt> and <t>pollLast</tt> that return and remove the
20 > * lowest and highest key, if one exists, else returning
21 > * <tt>null</tt>.
22   *
23   * <p> The return values of these methods may be ambiguous in
24   * implementations that permit <tt>null</tt> elements. However, even
25 < * in this case the result can be diambiguated by checking
26 < * <tt>contains(null)</tt>.
25 > * in this case the result can be disambiguated by checking
26 > * <tt>contains(null)</tt>. To avoid such issues, implementations of
27 > * this interface are encouraged <em>not</em> to permit insertion of
28 > * <tt>null</tt> elements. (Note that sorted sets of {@link
29 > * Comparable} elements intrinsically do not permit <tt>null</tt>.)
30   *
31   * @author Doug Lea
32   * @param <E> the type of elements maintained by this set
# Line 30 | Line 34 | import java.util.*;
34   public interface NavigableSet<E> extends SortedSet<E> {
35      /**
36       * Returns an element greater than or equal to the given element, or
37 <     * null if there is no such element.
37 >     * <tt>null</tt> if there is no such element.
38       *
39       * @param o the value to match
40 <     * @return an element greater than or equal to given element, or null
41 <     * if there is no such element.
40 >     * @return an element greater than or equal to given element, or
41 >     * <tt>null</tt> if there is no such element.
42       * @throws ClassCastException if o cannot be compared with the elements
43       *            currently in the set.
44       * @throws NullPointerException if o is <tt>null</tt>
# Line 43 | Line 47 | public interface NavigableSet<E> extends
47      public E ceiling(E o);
48  
49      /**
50 <     * Returns an element strictly less than the given element, or null if
51 <     * there is no such element.
50 >     * Returns an element strictly less than the given element, or
51 >     * <tt>null</tt> if there is no such element.
52       *
53       * @param o the value to match
54       * @return the greatest element less than the given element, or
55 <     * null if there is no such element.
55 >     * <tt>null</tt> if there is no such element.
56       * @throws ClassCastException if o cannot be compared with the elements
57       *            currently in the set.
58       * @throws NullPointerException if o is <tt>null</tt>
# Line 57 | Line 61 | public interface NavigableSet<E> extends
61      public E lower(E o);
62  
63      /**
64 <     * Returns an element less than or equal to the given element, or null
65 <     * if there is no such element.
64 >     * Returns an element less than or equal to the given element, or
65 >     * <tt>null</tt> if there is no such element.
66       *
67       * @param o the value to match
68       * @return the greatest element less than or equal to given
69 <     * element, or null if there is no such element.
69 >     * element, or <tt>null</tt> if there is no such element.
70       * @throws ClassCastException if o cannot be compared with the elements
71       *            currently in the set.
72       * @throws NullPointerException if o is <tt>null</tt>.
# Line 71 | Line 75 | public interface NavigableSet<E> extends
75      public E floor(E o);
76  
77      /**
78 <     * Returns an element strictly greater than the given element, or null
79 <     * if there is no such element.
78 >     * Returns an element strictly greater than the given element, or
79 >     * <tt>null</tt> if there is no such element.
80       *
81       * @param o the value to match
82       * @return the least element greater than the given element, or
83 <     * null if there is no such element.
83 >     * <tt>null</tt> if there is no such element.
84       * @throws ClassCastException if o cannot be compared with the elements
85       *            currently in the set.
86       * @throws NullPointerException if o is <tt>null</tt>
# Line 117 | Line 121 | public interface NavigableSet<E> extends
121       * @throws IllegalArgumentException if <tt>fromElement</tt> is
122       * greater than <tt>toElement</tt>.
123       * @throws NullPointerException if <tt>fromElement</tt> or
124 <     *         <tt>toElement</tt> is <tt>null</tt>.
124 >     *         <tt>toElement</tt> is <tt>null</tt>
125 >     * and this set deas not permit <tt>null</tt> elements
126       */
127      public NavigableSet<E> subSet(E fromElement, E toElement);
128  
# Line 132 | Line 137 | public interface NavigableSet<E> extends
137       * @throws ClassCastException if <tt>toElement</tt> is not compatible
138       *         with this set's comparator (or, if the set has no comparator,
139       *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
140 <     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>.
140 >     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
141 >     * and this set deas not permit <tt>null</tt> elements
142       */
143      public NavigableSet<E> headSet(E toElement);
144  
# Line 148 | Line 154 | public interface NavigableSet<E> extends
154       * compatible with this set's comparator (or, if the set has no
155       * comparator, if <tt>fromElement</tt> does not implement
156       * <tt>Comparable</tt>).
157 <     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>.
157 >     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
158 >     * and this set deas not permit <tt>null</tt> elements
159       */
160      public NavigableSet<E> tailSet(E fromElement);
161   }

Diff Legend

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