[cvs] / jsr166 / src / main / java / util / NavigableSet.java Repository:
ViewVC logotype

Annotation of /jsr166/src/main/java/util/NavigableSet.java

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.14 - (view) (download)

1 : dl 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
4 :     * http://creativecommons.org/licenses/publicdomain
5 :     */
6 :    
7 :     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 : jsr166 1.9 * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return elements
13 : dl 1.1 * respectively less than, less than or equal, greater than or equal,
14 : jsr166 1.9 * and greater than a given element, returning <tt>null</tt> if there is
15 :     * no such element. A <tt>NavigableSet</tt> may be viewed and traversed
16 : dl 1.1 * in either ascending or descending order. The <tt>Collection</tt>
17 :     * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
18 : jsr166 1.9 * the additional method <tt>descendingIterator</tt> returns a
19 : dl 1.1 * 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 : jsr166 1.9 * <tt>pollLast</tt> that return and remove the lowest and highest
23 :     * element, if one exists, else returning <tt>null</tt>.
24 : dl 1.4 * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
25 :     * <tt>navigableTailSet</tt> differ from the similarly named
26 : dl 1.11 * <tt>SortedSet</tt> methods only in their declared return types.
27 : jsr166 1.12 * Subsets of any <tt>NavigableSet</tt> must implement the
28 :     * <tt>NavigableSet</tt> interface.
29 : dl 1.1 *
30 :     * <p> The return values of navigation methods may be ambiguous in
31 :     * implementations that permit <tt>null</tt> 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 : jsr166 1.9 * this interface are encouraged to <em>not</em> permit insertion of
35 : dl 1.1 * <tt>null</tt> elements. (Note that sorted sets of {@link
36 :     * Comparable} elements intrinsically do not permit <tt>null</tt>.)
37 :     *
38 : jsr166 1.8 * <p>This interface is a member of the
39 :     * <a href="{@docRoot}/../guide/collections/index.html">
40 :     * Java Collections Framework</a>.
41 :     *
42 : dl 1.1 * @author Doug Lea
43 :     * @param <E> the type of elements maintained by this set
44 : jsr166 1.7 * @since 1.6
45 : dl 1.1 */
46 :     public interface NavigableSet<E> extends SortedSet<E> {
47 :     /**
48 : jsr166 1.9 * Returns the greatest element in this set strictly less than the
49 :     * given element, or <tt>null</tt> if there is no such element.
50 : jsr166 1.6 *
51 : jsr166 1.5 * @param e the value to match
52 : jsr166 1.9 * @return the greatest element less than <tt>e</tt>,
53 :     * or <tt>null</tt> if there is no such element
54 :     * @throws ClassCastException if the specified element cannot be
55 :     * compared with the elements currently in the set
56 :     * @throws NullPointerException if the specified element is null
57 :     * and this set does not permit null elements
58 : dl 1.1 */
59 : jsr166 1.9 E lower(E e);
60 : dl 1.1
61 :     /**
62 : jsr166 1.9 * Returns the greatest element in this set less than or equal to
63 :     * the given element, or <tt>null</tt> if there is no such element.
64 : jsr166 1.6 *
65 : jsr166 1.5 * @param e the value to match
66 : jsr166 1.9 * @return the greatest element less than or equal to <tt>e</tt>,
67 :     * or <tt>null</tt> if there is no such element
68 :     * @throws ClassCastException if the specified element cannot be
69 :     * compared with the elements currently in the set
70 :     * @throws NullPointerException if the specified element is null
71 :     * and this set does not permit null elements
72 : dl 1.1 */
73 : jsr166 1.9 E floor(E e);
74 : dl 1.1
75 :     /**
76 : jsr166 1.9 * Returns the least element in this set greater than or equal to
77 :     * the given element, or <tt>null</tt> if there is no such element.
78 : jsr166 1.6 *
79 : jsr166 1.5 * @param e the value to match
80 : jsr166 1.9 * @return the least element greater than or equal to <tt>e</tt>,
81 :     * or <tt>null</tt> if there is no such element
82 :     * @throws ClassCastException if the specified element cannot be
83 :     * compared with the elements currently in the set
84 :     * @throws NullPointerException if the specified element is null
85 :     * and this set does not permit null elements
86 : dl 1.1 */
87 : jsr166 1.9 E ceiling(E e);
88 : dl 1.1
89 :     /**
90 : jsr166 1.9 * Returns the least element in this set strictly greater than the
91 :     * given element, or <tt>null</tt> if there is no such element.
92 : jsr166 1.6 *
93 : jsr166 1.5 * @param e the value to match
94 : jsr166 1.9 * @return the least element greater than <tt>e</tt>,
95 :     * or <tt>null</tt> if there is no such element
96 :     * @throws ClassCastException if the specified element cannot be
97 :     * compared with the elements currently in the set
98 :     * @throws NullPointerException if the specified element is null
99 :     * and this set does not permit null elements
100 : dl 1.1 */
101 : jsr166 1.5 E higher(E e);
102 : dl 1.1
103 :     /**
104 : jsr166 1.13 * Retrieves and removes the first (lowest) element,
105 :     * or returns <tt>null</tt> if this set is empty.
106 : dl 1.1 *
107 : jsr166 1.9 * @return the first element, or <tt>null</tt> if this set is empty
108 : dl 1.1 */
109 : dl 1.3 E pollFirst();
110 : dl 1.1
111 :     /**
112 : jsr166 1.13 * Retrieves and removes the last (highest) element,
113 :     * or returns <tt>null</tt> if this set is empty.
114 : dl 1.1 *
115 : jsr166 1.9 * @return the last element, or <tt>null</tt> if this set is empty
116 : dl 1.1 */
117 : dl 1.3 E pollLast();
118 : dl 1.1
119 :     /**
120 : jsr166 1.10 * Returns an iterator over the elements in this set, in ascending order.
121 : jsr166 1.6 *
122 : jsr166 1.10 * @return an iterator over the elements in this set, in ascending order
123 :     */
124 :     Iterator<E> iterator();
125 :    
126 :     /**
127 :     * Returns an iterator over the elements in this set, in descending order.
128 :     *
129 :     * @return an iterator over the elements in this set, in descending order
130 : dl 1.1 */
131 :     Iterator<E> descendingIterator();
132 :    
133 :     /**
134 : dl 1.3 * Returns a view of the portion of this set whose elements range
135 :     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
136 :     * exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are
137 : jsr166 1.9 * equal, the returned set is empty.) The returned set is backed
138 :     * by this set, so changes in the returned set are reflected in
139 :     * this set, and vice-versa. The returned set supports all
140 :     * optional set operations that this set supports.
141 : dl 1.3 *
142 : jsr166 1.9 * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
143 :     * on an attempt to insert an element outside its range.
144 :     *
145 :     * @param fromElement low endpoint (inclusive) of the returned set
146 :     * @param toElement high endpoint (exclusive) of the returned set
147 : dl 1.1 * @return a view of the portion of this set whose elements range from
148 : jsr166 1.9 * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive
149 : dl 1.1 * @throws ClassCastException if <tt>fromElement</tt> and
150 : jsr166 1.9 * <tt>toElement</tt> cannot be compared to one another using this
151 :     * set's comparator (or, if the set has no comparator, using
152 :     * natural ordering). Implementations may, but are not required
153 :     * to, throw this exception if <tt>fromElement</tt> or
154 :     * <tt>toElement</tt> cannot be compared to elements currently in
155 :     * the set.
156 :     * @throws NullPointerException if <tt>fromElement</tt> or
157 :     * <tt>toElement</tt> is null and this set does
158 :     * not permit null elements
159 : dl 1.1 * @throws IllegalArgumentException if <tt>fromElement</tt> is
160 : jsr166 1.9 * greater than <tt>toElement</tt>; or if this set itself
161 :     * has a restricted range, and <tt>fromElement</tt> or
162 :     * <tt>toElement</tt> lies outside the bounds of the range.
163 : dl 1.1 */
164 : dl 1.3 NavigableSet<E> navigableSubSet(E fromElement, E toElement);
165 : dl 1.1
166 :     /**
167 : dl 1.3 * Returns a view of the portion of this set whose elements are
168 : jsr166 1.9 * strictly less than <tt>toElement</tt>. The returned set is
169 :     * backed by this set, so changes in the returned set are
170 :     * reflected in this set, and vice-versa. The returned set
171 :     * supports all optional set operations that this set supports.
172 :     *
173 :     * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
174 :     * on an attempt to insert an element outside its range.
175 :     *
176 :     * @param toElement high endpoint (exclusive) of the returned set
177 : dl 1.1 * @return a view of the portion of this set whose elements are strictly
178 : jsr166 1.9 * less than <tt>toElement</tt>
179 : dl 1.1 * @throws ClassCastException if <tt>toElement</tt> is not compatible
180 :     * with this set's comparator (or, if the set has no comparator,
181 : jsr166 1.9 * if <tt>toElement</tt> does not implement {@link Comparable}).
182 :     * Implementations may, but are not required to, throw this
183 :     * exception if <tt>toElement</tt> cannot be compared to elements
184 :     * currently in the set.
185 :     * @throws NullPointerException if <tt>toElement</tt> is null and
186 :     * this set does not permit null elements
187 :     * @throws IllegalArgumentException if this set itself has a
188 :     * restricted range, and <tt>toElement</tt> lies outside the
189 :     * bounds of the range
190 : dl 1.1 */
191 : dl 1.3 NavigableSet<E> navigableHeadSet(E toElement);
192 : dl 1.1
193 :     /**
194 :     * Returns a view of the portion of this set whose elements are
195 :     * greater than or equal to <tt>fromElement</tt>. The returned
196 : jsr166 1.9 * set is backed by this set, so changes in the returned set are
197 :     * reflected in this set, and vice-versa. The returned set
198 :     * supports all optional set operations that this set supports.
199 :     *
200 :     * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
201 :     * on an attempt to insert an element outside its range.
202 :     *
203 :     * @param fromElement low endpoint (inclusive) of the returned set
204 :     * @return a view of the portion of this set whose elements are greater
205 :     * than or equal to <tt>fromElement</tt>
206 :     * @throws ClassCastException if <tt>fromElement</tt> is not compatible
207 :     * with this set's comparator (or, if the set has no comparator,
208 :     * if <tt>fromElement</tt> does not implement {@link Comparable}).
209 :     * Implementations may, but are not required to, throw this
210 :     * exception if <tt>fromElement</tt> cannot be compared to elements
211 :     * currently in the set.
212 :     * @throws NullPointerException if <tt>fromElement</tt> is null
213 :     * and this set does not permit null elements
214 :     * @throws IllegalArgumentException if this set itself has a
215 :     * restricted range, and <tt>fromElement</tt> lies outside the
216 :     * bounds of the range
217 : dl 1.1 */
218 : dl 1.3 NavigableSet<E> navigableTailSet(E fromElement);
219 : dl 1.1 }

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8