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.3 by dl, Tue Mar 22 01:30:10 2005 UTC vs.
Revision 1.16 by dl, Thu Apr 20 20:34:37 2006 UTC

# Line 1 | Line 1
1   /*
2 < * Written by Doug Lea with assistance from members of JCP JSR-166
3 < * Expert Group and released to the public domain, as explained at
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
5   */
6  
# Line 8 | Line 8 | package java.util;
8  
9   /**
10   * A {@link SortedSet} extended with navigation methods reporting
11 < * closest matches for given search targets. Methods <tt>lower</tt>,
12 < * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys
11 > * closest matches for given search targets. Methods <tt>lower},
12 > * {@code floor}, {@code ceiling}, and {@code higher} return elements
13   * respectively less than, less than or equal, greater than or equal,
14 < * and greater than a given key, returning <tt>null</tt> if there is
15 < * no such key.  A <tt>NavigableSet</tt> may be viewed and traversed
16 < * in either ascending or descending order.  The <tt>Collection</tt>
17 < * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
18 < * the additional method <tt>descendingIterator</tt> returns
19 < * descending iterator. The performance of ascending traversals is
20 < * likely to be faster than descending traversals.  This interface
21 < * additionally defines methods <tt>pollFirst</tt> and
22 < * <t>pollLast</tt> that return and remove the lowest and highest key,
23 < * if one exists, else returning <tt>null</tt>.
14 > * and greater than a given element, returning {@code null} if there
15 > * is no such element.  A {@code NavigableSet} may be accessed and
16 > * traversed in either ascending or descending order.  The {@code
17 > * descendingSet} method returns a view of the set with the senses of
18 > * all relational and directional methods inverted. The performance of
19 > * ascending operations and views is likely to be faster than that of
20 > * descending ones.  This interface additionally defines methods
21 > * {@code pollFirst} and {@code pollLast} that return and remove the
22 > * lowest and highest element, if one exists, else returning {@code
23 > * null}.  Methods {@code subSet}, {@code headSet},
24 > * and {@code tailSet} differ from the like-named {@code
25 > * SortedSet} methods in accepting additional arguments describing
26 > * whether lower and upper bounds are inclusive versus exclusive.
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
31 < * implementations that permit <tt>null</tt> elements. However, even
31 > * implementations that permit {@code null} elements. However, even
32   * in this case the result can be disambiguated by checking
33 < * <tt>contains(null)</tt>. To avoid such issues, implementations of
34 < * this interface are encouraged <em>not</em> to permit insertion of
35 < * <tt>null</tt> elements. (Note that sorted sets of {@link
36 < * Comparable} elements intrinsically do not permit <tt>null</tt>.)
33 > * {@code contains(null)}. To avoid such issues, implementations of
34 > * this interface are encouraged to <em>not</em> permit insertion of
35 > * {@code null} elements. (Note that sorted sets of {@link
36 > * Comparable} elements intrinsically do not permit {@code null}.)
37 > *
38 > * <p>This interface is a member of the
39 > * <a href="{@docRoot}/../guide/collections/index.html">
40 > * Java Collections Framework</a>.
41   *
42   * @author Doug Lea
43 + * @author Josh Bloch
44   * @param <E> the type of elements maintained by this set
45 + * @since 1.6
46   */
47   public interface NavigableSet<E> extends SortedSet<E> {
48      /**
49 <     * Returns an element greater than or equal to the given element, or
50 <     * <tt>null</tt> if there is no such element.
51 <     *
52 <     * @param o the value to match
53 <     * @return an element greater than or equal to given element, or
54 <     * <tt>null</tt> if there is no such element.
55 <     * @throws ClassCastException if o cannot be compared with the elements
56 <     *            currently in the set.
57 <     * @throws NullPointerException if o is <tt>null</tt>
58 <     * and this set does not permit <tt>null</tt> elements
59 <     */
60 <    E ceiling(E o);
61 <
62 <    /**
63 <     * Returns an element strictly less than the given element, or
64 <     * <tt>null</tt> if there is no such element.
65 <     *
66 <     * @param o the value to match
67 <     * @return the greatest element less than the given element, or
68 <     * <tt>null</tt> if there is no such element.
69 <     * @throws ClassCastException if o cannot be compared with the elements
70 <     *            currently in the set.
71 <     * @throws NullPointerException if o is <tt>null</tt>
72 <     * and this set does not permit <tt>null</tt> elements
62 <     */
63 <    E lower(E o);
64 <
65 <    /**
66 <     * Returns an element less than or equal to the given element, or
67 <     * <tt>null</tt> if there is no such element.
68 <     *
69 <     * @param o the value to match
70 <     * @return the greatest element less than or equal to given
71 <     * element, or <tt>null</tt> if there is no such element.
72 <     * @throws ClassCastException if o cannot be compared with the elements
73 <     *            currently in the set.
74 <     * @throws NullPointerException if o is <tt>null</tt>.
75 <     * and this set does not permit <tt>null</tt> elements
76 <     */
77 <    E floor(E o);
78 <
79 <    /**
80 <     * Returns an element strictly greater than the given element, or
81 <     * <tt>null</tt> if there is no such element.
82 <     *
83 <     * @param o the value to match
84 <     * @return the least element greater than the given element, or
85 <     * <tt>null</tt> if there is no such element.
86 <     * @throws ClassCastException if o cannot be compared with the elements
87 <     *            currently in the set.
88 <     * @throws NullPointerException if o is <tt>null</tt>
89 <     * and this set does not permit <tt>null</tt> elements
49 >     * Returns the greatest element in this set strictly less than the
50 >     * given element, or {@code null} if there is no such element.
51 >     *
52 >     * @param e the value to match
53 >     * @return the greatest element less than {@code e},
54 >     *         or {@code null} if there is no such element
55 >     * @throws ClassCastException if the specified element cannot be
56 >     *         compared with the elements currently in the set
57 >     * @throws NullPointerException if the specified element is null
58 >     *         and this set does not permit null elements
59 >     */
60 >    E lower(E e);
61 >
62 >    /**
63 >     * Returns the greatest element in this set less than or equal to
64 >     * the given element, or {@code null} if there is no such element.
65 >     *
66 >     * @param e the value to match
67 >     * @return the greatest element less than or equal to {@code e},
68 >     *         or {@code null} if there is no such element
69 >     * @throws ClassCastException if the specified element cannot be
70 >     *         compared with the elements currently in the set
71 >     * @throws NullPointerException if the specified element is null
72 >     *         and this set does not permit null elements
73       */
74 <    E higher(E o);
74 >    E floor(E e);
75  
76      /**
77 <     * Retrieves and removes the first (lowest) element.
77 >     * Returns the least element in this set greater than or equal to
78 >     * the given element, or {@code null} if there is no such element.
79       *
80 <     * @return the first element, or <tt>null</tt> if empty.
80 >     * @param e the value to match
81 >     * @return the least element greater than or equal to {@code e},
82 >     *         or {@code null} if there is no such element
83 >     * @throws ClassCastException if the specified element cannot be
84 >     *         compared with the elements currently in the set
85 >     * @throws NullPointerException if the specified element is null
86 >     *         and this set does not permit null elements
87 >     */
88 >    E ceiling(E e);
89 >
90 >    /**
91 >     * Returns the least element in this set strictly greater than the
92 >     * given element, or {@code null} if there is no such element.
93 >     *
94 >     * @param e the value to match
95 >     * @return the least element greater than {@code e},
96 >     *         or {@code null} if there is no such element
97 >     * @throws ClassCastException if the specified element cannot be
98 >     *         compared with the elements currently in the set
99 >     * @throws NullPointerException if the specified element is null
100 >     *         and this set does not permit null elements
101 >     */
102 >    E higher(E e);
103 >
104 >    /**
105 >     * Retrieves and removes the first (lowest) element,
106 >     * or returns {@code null} if this set is empty.
107 >     *
108 >     * @return the first element, or {@code null} if this set is empty
109       */
110      E pollFirst();
111  
112      /**
113 <     * Retrieves and removes the last (highest) element.
113 >     * Retrieves and removes the last (highest) element,
114 >     * or returns {@code null} if this set is empty.
115       *
116 <     * @return the last element, or <tt>null</tt> if empty.
116 >     * @return the last element, or {@code null} if this set is empty
117       */
118      E pollLast();
119  
120      /**
121 <     * Returns an iterator over the elements in this collection, in
122 <     * descending order.  
123 <     *
124 <     * @return an <tt>Iterator</tt> over the elements in this collection
121 >     * Returns an iterator over the elements in this set, in ascending order.
122 >     *
123 >     * @return an iterator over the elements in this set, in ascending order
124 >     */
125 >    Iterator<E> iterator();
126 >
127 >    /**
128 >     * Returns a {@link NavigableSet} view of the elements contained in this
129 >     * set in descending order.  The descending set is backed by this set, so
130 >     * changes to the set are reflected in the descending set, and vice-versa.
131 >     * If either set is modified while an iteration over the other set is in
132 >     * in progress (except through the iterator's own {@code remove} operation),
133 >     * the results of the iteration are undefined.
134 >     *
135 >     * @return a navigable set view of the mappings contained in this set,
136 >     *     sorted in descending order
137 >     */
138 >    NavigableSet<E> descendingSet();
139 >
140 >    /**
141 >     * Returns an iterator over the elements in this set, in descending order.
142 >     * Equivalent in effect to <tt>descendingSet().iterator()</tt>.
143 >     *
144 >     * @return an iterator over the elements in this set, in descending order
145       */
146      Iterator<E> descendingIterator();
147  
148      /**
149 <     * Returns a view of the portion of this set whose elements range
150 <     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
151 <     * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are
152 <     * equal, the returned navigable set is empty.)  The returned
153 <     * navigable set is backed by this set, so changes in the returned
154 <     * navigable set are reflected in this set, and vice-versa. Note:
155 <     * This method differs from <tt>SortedSet.subSet</tt> only in that
156 <     * the returned set is guaranteed to support the
157 <     * <tt>NavigableSet</tt> interface.
149 >     * Returns a view of the portion of this set whose elements range from
150 >     * {@code fromElement} to {@code toElement}.  If {@code fromElement} and
151 >     * {@code toElement} are equal, the returned set is empty unless {@code
152 >     * fromExclusive} and {@code toExclusive} are both true.  The returned set
153 >     * is backed by this set, so changes in the returned set are reflected in
154 >     * this set, and vice-versa.  The returned set supports all optional set
155 >     * operations that this set supports.
156 >     *
157 >     * <p>The returned set will throw an {@code IllegalArgumentException}
158 >     * on an attempt to insert an element outside its range.
159       *
160 <     * @param fromElement low endpoint (inclusive) of the subSet.
161 <     * @param toElement high endpoint (exclusive) of the subSet.
160 >     * @param fromElement low endpoint of the returned set
161 >     * @param fromInclusive true if the low endpoint ({@code fromElement}) is
162 >     *        to be included in the the returned view
163 >     * @param toElement high endpoint of the returned set
164 >     * @param toInclusive true if the high endpoint ({@code toElement}) is
165 >     *        to be included in the the returned view
166       * @return a view of the portion of this set whose elements range from
167 <     *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
168 <     *         exclusive.
169 <     * @throws ClassCastException if <tt>fromElement</tt> and
170 <     *         <tt>toElement</tt> cannot be compared to one another using
171 <     *         this set's comparator (or, if the set has no comparator,
172 <     *         using natural ordering).
173 <     * @throws IllegalArgumentException if <tt>fromElement</tt> is
174 <     * greater than <tt>toElement</tt>.
175 <     * @throws NullPointerException if <tt>fromElement</tt> or
176 <     *         <tt>toElement</tt> is <tt>null</tt>
177 <     * and this set does not permit <tt>null</tt> elements
178 <     */
179 <    NavigableSet<E> navigableSubSet(E fromElement, E toElement);
180 <
181 <    /**
182 <     * Returns a view of the portion of this set whose elements are
183 <     * strictly less than <tt>toElement</tt>.  The returned navigable
184 <     * set is backed by this set, so changes in the returned navigable
185 <     * set are reflected in this set, and vice-versa.
186 <     * @param toElement high endpoint (exclusive) of the headSet.
187 <     * @return a view of the portion of this set whose elements are strictly
188 <     *         less than toElement.
189 <     * @throws ClassCastException if <tt>toElement</tt> is not compatible
167 >     *         {@code fromElement}, inclusive, to {@code toElement}, exclusive
168 >     * @throws ClassCastException if {@code fromElement} and
169 >     *         {@code toElement} cannot be compared to one another using this
170 >     *         set's comparator (or, if the set has no comparator, using
171 >     *         natural ordering).  Implementations may, but are not required
172 >     *         to, throw this exception if {@code fromElement} or
173 >     *         {@code toElement} cannot be compared to elements currently in
174 >     *         the set.
175 >     * @throws NullPointerException if {@code fromElement} or
176 >     *         {@code toElement} is null and this set does
177 >     *         not permit null elements
178 >     * @throws IllegalArgumentException if {@code fromElement} is
179 >     *         greater than {@code toElement}; or if this set itself
180 >     *         has a restricted range, and {@code fromElement} or
181 >     *         {@code toElement} lies outside the bounds of the range.
182 >     */
183 >    NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
184 >                           E toElement,   boolean toInclusive);
185 >
186 >    /**
187 >     * Returns a view of the portion of this set whose elements are less than
188 >     * (or equal to, if {@code inclusive} is true) {@code toElement}.  The
189 >     * returned set is backed by this set, so changes in the returned set are
190 >     * reflected in this set, and vice-versa.  The returned set supports all
191 >     * optional set operations that this set supports.
192 >     *
193 >     * <p>The returned set will throw an {@code IllegalArgumentException}
194 >     * on an attempt to insert an element outside its range.
195 >     *
196 >     * @param toElement high endpoint of the returned set
197 >     * @param inclusive true if the high endpoint ({@code toElement}) is
198 >     *        to be included in the the returned view
199 >     * @return a view of the portion of this set whose elements are less than
200 >     *         (or equal to, if {@code inclusive} is true) {@code toElement}
201 >     * @throws ClassCastException if {@code toElement} is not compatible
202 >     *         with this set's comparator (or, if the set has no comparator,
203 >     *         if {@code toElement} does not implement {@link Comparable}).
204 >     *         Implementations may, but are not required to, throw this
205 >     *         exception if {@code toElement} cannot be compared to elements
206 >     *         currently in the set.
207 >     * @throws NullPointerException if {@code toElement} is null and
208 >     *         this set does not permit null elements
209 >     * @throws IllegalArgumentException if this set itself has a
210 >     *         restricted range, and {@code toElement} lies outside the
211 >     *         bounds of the range
212 >     */
213 >    NavigableSet<E> headSet(E toElement, boolean inclusive);
214 >
215 >    /**
216 >     * Returns a view of the portion of this set whose elements are greater
217 >     * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
218 >     * The returned set is backed by this set, so changes in the returned set
219 >     * are reflected in this set, and vice-versa.  The returned set supports
220 >     * all optional set operations that this set supports.
221 >     *
222 >     * <p>The returned set will throw an {@code IllegalArgumentException}
223 >     * on an attempt to insert an element outside its range.
224 >     *
225 >     * @param fromElement low endpoint of the returned set
226 >     * @param inclusive true if the low endpoint ({@code fromElement}) is
227 >     *        to be included in the the returned view
228 >     * @return a view of the portion of this set whose elements are greater
229 >     *         than or equal to {@code fromElement}
230 >     * @throws ClassCastException if {@code fromElement} is not compatible
231       *         with this set's comparator (or, if the set has no comparator,
232 <     *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
233 <     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
234 <     * and this set does not permit <tt>null</tt> elements
235 <     */
236 <    NavigableSet<E> navigableHeadSet(E toElement);
237 <
238 <    /**
239 <     * Returns a view of the portion of this set whose elements are
240 <     * greater than or equal to <tt>fromElement</tt>.  The returned
162 <     * navigable set is backed by this set, so changes in the returned
163 <     * navigable set are reflected in this set, and vice-versa.
164 <     * @param fromElement low endpoint (inclusive) of the tailSet.
165 <     * @return a view of the portion of this set whose elements are
166 <     * greater than or equal to <tt>fromElement</tt>.
167 <     * @throws ClassCastException if <tt>fromElement</tt> is not
168 <     * compatible with this set's comparator (or, if the set has no
169 <     * comparator, if <tt>fromElement</tt> does not implement
170 <     * <tt>Comparable</tt>).
171 <     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
172 <     * and this set does not permit <tt>null</tt> elements
232 >     *         if {@code fromElement} does not implement {@link Comparable}).
233 >     *         Implementations may, but are not required to, throw this
234 >     *         exception if {@code fromElement} cannot be compared to elements
235 >     *         currently in the set.
236 >     * @throws NullPointerException if {@code fromElement} is null
237 >     *         and this set does not permit null elements
238 >     * @throws IllegalArgumentException if this set itself has a
239 >     *         restricted range, and {@code fromElement} lies outside the
240 >     *         bounds of the range
241       */
242 <    NavigableSet<E> navigableTailSet(E fromElement);
242 >    NavigableSet<E> tailSet(E fromElement, boolean inclusive);
243   }

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines