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/publicdomain/zero/1.0/ |
5 |
*/ |
6 |
|
7 |
package jsr166x; |
8 |
|
9 |
import java.util.*; |
10 |
|
11 |
/** |
12 |
* A {@link SortedSet} extended with navigation methods reporting |
13 |
* closest matches for given search targets. Methods {@code lower}, |
14 |
* {@code floor}, {@code ceiling}, and {@code higher} return keys |
15 |
* respectively less than, less than or equal, greater than or equal, |
16 |
* and greater than a given key, returning {@code null} if there is |
17 |
* no such key. A {@code NavigableSet} may be viewed and traversed |
18 |
* in either ascending or descending order. The {@code Collection} |
19 |
* {@code iterator} method returns an ascending {@code Iterator} and |
20 |
* the additional method {@code descendingIterator} returns |
21 |
* descending iterator. The performance of ascending traversals is |
22 |
* likely to be faster than descending traversals. This interface |
23 |
* additionally defines methods {@code pollFirst} and |
24 |
* {@code pollLast} that return and remove the lowest and highest key, |
25 |
* if one exists, else returning {@code null}. |
26 |
* |
27 |
* <p>The return values of navigation methods may be ambiguous in |
28 |
* implementations that permit {@code null} elements. However, even |
29 |
* in this case the result can be disambiguated by checking |
30 |
* {@code contains(null)}. To avoid such issues, implementations of |
31 |
* this interface are encouraged <em>not</em> to permit insertion of |
32 |
* {@code null} elements. (Note that sorted sets of {@link |
33 |
* Comparable} elements intrinsically do not permit {@code null}.) |
34 |
* |
35 |
* @author Doug Lea |
36 |
* @param <E> the type of elements maintained by this set |
37 |
*/ |
38 |
public interface NavigableSet<E> extends SortedSet<E> { |
39 |
/** |
40 |
* Returns an element greater than or equal to the given element, or |
41 |
* {@code null} if there is no such element. |
42 |
* |
43 |
* @param o the value to match |
44 |
* @return an element greater than or equal to given element, or |
45 |
* {@code null} if there is no such element |
46 |
* @throws ClassCastException if o cannot be compared with the elements |
47 |
* currently in the set |
48 |
* @throws NullPointerException if o is {@code null} |
49 |
* and this set deas not permit {@code null} elements |
50 |
*/ |
51 |
public E ceiling(E o); |
52 |
|
53 |
/** |
54 |
* Returns an element strictly less than the given element, or |
55 |
* {@code null} if there is no such element. |
56 |
* |
57 |
* @param o the value to match |
58 |
* @return the greatest element less than the given element, or |
59 |
* {@code null} if there is no such element |
60 |
* @throws ClassCastException if o cannot be compared with the elements |
61 |
* currently in the set |
62 |
* @throws NullPointerException if o is {@code null} |
63 |
* and this set deas not permit {@code null} elements |
64 |
*/ |
65 |
public E lower(E o); |
66 |
|
67 |
/** |
68 |
* Returns an element less than or equal to the given element, or |
69 |
* {@code null} if there is no such element. |
70 |
* |
71 |
* @param o the value to match |
72 |
* @return the greatest element less than or equal to given |
73 |
* element, or {@code null} if there is no such element |
74 |
* @throws ClassCastException if o cannot be compared with the elements |
75 |
* currently in the set |
76 |
* @throws NullPointerException if o is {@code null} |
77 |
* and this set deas not permit {@code null} elements |
78 |
*/ |
79 |
public E floor(E o); |
80 |
|
81 |
/** |
82 |
* Returns an element strictly greater than the given element, or |
83 |
* {@code null} if there is no such element. |
84 |
* |
85 |
* @param o the value to match |
86 |
* @return the least element greater than the given element, or |
87 |
* {@code null} if there is no such element |
88 |
* @throws ClassCastException if o cannot be compared with the elements |
89 |
* currently in the set |
90 |
* @throws NullPointerException if o is {@code null} |
91 |
* and this set deas not permit {@code null} elements |
92 |
*/ |
93 |
public E higher(E o); |
94 |
|
95 |
/** |
96 |
* Retrieves and removes the first (lowest) element. |
97 |
* |
98 |
* @return the first element, or {@code null} if empty |
99 |
*/ |
100 |
public E pollFirst(); |
101 |
|
102 |
/** |
103 |
* Retrieves and removes the last (highest) element. |
104 |
* |
105 |
* @return the last element, or {@code null} if empty |
106 |
*/ |
107 |
public E pollLast(); |
108 |
|
109 |
/** |
110 |
* Returns an iterator over the elements in this collection, in |
111 |
* descending order. |
112 |
* |
113 |
* @return an {@code Iterator} over the elements in this collection |
114 |
*/ |
115 |
Iterator<E> descendingIterator(); |
116 |
|
117 |
/** |
118 |
* Returns a view of the portion of this set whose elements range from |
119 |
* {@code fromElement}, inclusive, to {@code toElement}, exclusive. (If |
120 |
* {@code fromElement} and {@code toElement} are equal, the returned |
121 |
* sorted set is empty.) The returned sorted set is backed by this set, |
122 |
* so changes in the returned sorted set are reflected in this set, and |
123 |
* vice-versa. |
124 |
* @param fromElement low endpoint (inclusive) of the subSet |
125 |
* @param toElement high endpoint (exclusive) of the subSet |
126 |
* @return a view of the portion of this set whose elements range from |
127 |
* {@code fromElement}, inclusive, to {@code toElement}, |
128 |
* exclusive |
129 |
* @throws ClassCastException if {@code fromElement} and |
130 |
* {@code toElement} cannot be compared to one another using |
131 |
* this set's comparator (or, if the set has no comparator, |
132 |
* using natural ordering) |
133 |
* @throws IllegalArgumentException if {@code fromElement} is |
134 |
* greater than {@code toElement} |
135 |
* @throws NullPointerException if {@code fromElement} or |
136 |
* {@code toElement} is {@code null} |
137 |
* and this set deas not permit {@code null} elements |
138 |
*/ |
139 |
public NavigableSet<E> subSet(E fromElement, E toElement); |
140 |
|
141 |
/** |
142 |
* Returns a view of the portion of this set whose elements are strictly |
143 |
* less than {@code toElement}. The returned sorted set is backed by |
144 |
* this set, so changes in the returned sorted set are reflected in this |
145 |
* set, and vice-versa. |
146 |
* @param toElement high endpoint (exclusive) of the headSet |
147 |
* @return a view of the portion of this set whose elements are strictly |
148 |
* less than toElement |
149 |
* @throws ClassCastException if {@code toElement} is not compatible |
150 |
* with this set's comparator (or, if the set has no comparator, |
151 |
* if {@code toElement} does not implement {@code Comparable}) |
152 |
* @throws NullPointerException if {@code toElement} is {@code null} |
153 |
* and this set deas not permit {@code null} elements |
154 |
*/ |
155 |
public NavigableSet<E> headSet(E toElement); |
156 |
|
157 |
/** |
158 |
* Returns a view of the portion of this set whose elements are |
159 |
* greater than or equal to {@code fromElement}. The returned |
160 |
* sorted set is backed by this set, so changes in the returned |
161 |
* sorted set are reflected in this set, and vice-versa. |
162 |
* @param fromElement low endpoint (inclusive) of the tailSet |
163 |
* @return a view of the portion of this set whose elements are |
164 |
* greater than or equal to {@code fromElement} |
165 |
* @throws ClassCastException if {@code fromElement} is not |
166 |
* compatible with this set's comparator (or, if the set has no |
167 |
* comparator, if {@code fromElement} does not implement |
168 |
* {@code Comparable}) |
169 |
* @throws NullPointerException if {@code fromElement} is {@code null} |
170 |
* and this set deas not permit {@code null} elements |
171 |
*/ |
172 |
public NavigableSet<E> tailSet(E fromElement); |
173 |
} |