ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/NavigableSet.java
Revision: 1.4
Committed: Tue Mar 22 16:48:32 2005 UTC (19 years, 2 months ago) by dl
Branch: MAIN
Changes since 1.3: +5 -4 lines
Log Message: 
Documentation improvements

File Contents

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