[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.7 - (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 :     * <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 : dl 1.4 * 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 : dl 1.1 *
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 : jsr166 1.7 * @since 1.6
40 : dl 1.1 */
41 :     public interface NavigableSet<E> extends SortedSet<E> {
42 :     /**
43 :     * Returns an element greater than or equal to the given element, or
44 :     * <tt>null</tt> if there is no such element.
45 : jsr166 1.6 *
46 : jsr166 1.5 * @param e the value to match
47 : dl 1.1 * @return an element greater than or equal to given element, or
48 :     * <tt>null</tt> if there is no such element.
49 : jsr166 1.5 * @throws ClassCastException if e cannot be compared with the elements
50 : dl 1.1 * currently in the set.
51 : jsr166 1.6 * @throws NullPointerException if e is <tt>null</tt>
52 : dl 1.2 * and this set does not permit <tt>null</tt> elements
53 : dl 1.1 */
54 : jsr166 1.5 E ceiling(E e);
55 : dl 1.1
56 :     /**
57 :     * Returns an element strictly less than the given element, or
58 :     * <tt>null</tt> if there is no such element.
59 : jsr166 1.6 *
60 : jsr166 1.5 * @param e the value to match
61 : dl 1.1 * @return the greatest element less than the given element, or
62 :     * <tt>null</tt> if there is no such element.
63 : jsr166 1.5 * @throws ClassCastException if e cannot be compared with the elements
64 : dl 1.1 * currently in the set.
65 : jsr166 1.5 * @throws NullPointerException if e is <tt>null</tt>
66 : dl 1.2 * and this set does not permit <tt>null</tt> elements
67 : dl 1.1 */
68 : jsr166 1.5 E lower(E e);
69 : dl 1.1
70 :     /**
71 :     * Returns an element less than or equal to the given element, or
72 :     * <tt>null</tt> if there is no such element.
73 : jsr166 1.6 *
74 : jsr166 1.5 * @param e the value to match
75 : dl 1.1 * @return the greatest element less than or equal to given
76 :     * element, or <tt>null</tt> if there is no such element.
77 : jsr166 1.5 * @throws ClassCastException if e cannot be compared with the elements
78 : dl 1.1 * currently in the set.
79 : jsr166 1.5 * @throws NullPointerException if e is <tt>null</tt>.
80 : dl 1.2 * and this set does not permit <tt>null</tt> elements
81 : dl 1.1 */
82 : jsr166 1.5 E floor(E e);
83 : dl 1.1
84 :     /**
85 :     * Returns an element strictly greater than the given element, or
86 :     * <tt>null</tt> if there is no such element.
87 : jsr166 1.6 *
88 : jsr166 1.5 * @param e the value to match
89 : dl 1.1 * @return the least element greater than the given element, or
90 :     * <tt>null</tt> if there is no such element.
91 : jsr166 1.5 * @throws ClassCastException if e cannot be compared with the elements
92 : dl 1.1 * currently in the set.
93 : jsr166 1.5 * @throws NullPointerException if e is <tt>null</tt>
94 : dl 1.2 * and this set does not permit <tt>null</tt> elements
95 : dl 1.1 */
96 : jsr166 1.5 E higher(E e);
97 : dl 1.1
98 :     /**
99 :     * Retrieves and removes the first (lowest) element.
100 :     *
101 :     * @return the first element, or <tt>null</tt> if empty.
102 :     */
103 : dl 1.3 E pollFirst();
104 : dl 1.1
105 :     /**
106 :     * Retrieves and removes the last (highest) element.
107 :     *
108 :     * @return the last element, or <tt>null</tt> if empty.
109 :     */
110 : dl 1.3 E pollLast();
111 : dl 1.1
112 :     /**
113 :     * Returns an iterator over the elements in this collection, in
114 : jsr166 1.6 * descending order.
115 :     *
116 : dl 1.1 * @return an <tt>Iterator</tt> over the elements in this collection
117 :     */
118 :     Iterator<E> descendingIterator();
119 :    
120 :     /**
121 : dl 1.3 * Returns a view of the portion of this set whose elements range
122 :     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
123 :     * exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are
124 :     * equal, the returned navigable set is empty.) The returned
125 :     * navigable set is backed by this set, so changes in the returned
126 : jsr166 1.6 * navigable set are reflected in this set, and vice-versa.
127 : dl 1.3 *
128 : dl 1.1 * @param fromElement low endpoint (inclusive) of the subSet.
129 :     * @param toElement high endpoint (exclusive) of the subSet.
130 :     * @return a view of the portion of this set whose elements range from
131 :     * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
132 :     * exclusive.
133 :     * @throws ClassCastException if <tt>fromElement</tt> and
134 :     * <tt>toElement</tt> cannot be compared to one another using
135 :     * this set's comparator (or, if the set has no comparator,
136 :     * using natural ordering).
137 :     * @throws IllegalArgumentException if <tt>fromElement</tt> is
138 :     * greater than <tt>toElement</tt>.
139 :     * @throws NullPointerException if <tt>fromElement</tt> or
140 : jsr166 1.6 * <tt>toElement</tt> is <tt>null</tt>
141 : dl 1.2 * and this set does not permit <tt>null</tt> elements
142 : dl 1.1 */
143 : dl 1.3 NavigableSet<E> navigableSubSet(E fromElement, E toElement);
144 : dl 1.1
145 :     /**
146 : dl 1.3 * Returns a view of the portion of this set whose elements are
147 :     * strictly less than <tt>toElement</tt>. The returned navigable
148 :     * set is backed by this set, so changes in the returned navigable
149 :     * set are reflected in this set, and vice-versa.
150 : dl 1.1 * @param toElement high endpoint (exclusive) of the headSet.
151 :     * @return a view of the portion of this set whose elements are strictly
152 :     * less than toElement.
153 :     * @throws ClassCastException if <tt>toElement</tt> is not compatible
154 :     * with this set's comparator (or, if the set has no comparator,
155 :     * if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
156 :     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
157 : dl 1.2 * and this set does not permit <tt>null</tt> elements
158 : dl 1.1 */
159 : dl 1.3 NavigableSet<E> navigableHeadSet(E toElement);
160 : dl 1.1
161 :     /**
162 :     * Returns a view of the portion of this set whose elements are
163 :     * greater than or equal to <tt>fromElement</tt>. The returned
164 : dl 1.3 * navigable set is backed by this set, so changes in the returned
165 :     * navigable set are reflected in this set, and vice-versa.
166 : dl 1.1 * @param fromElement low endpoint (inclusive) of the tailSet.
167 :     * @return a view of the portion of this set whose elements are
168 :     * greater than or equal to <tt>fromElement</tt>.
169 :     * @throws ClassCastException if <tt>fromElement</tt> is not
170 :     * compatible with this set's comparator (or, if the set has no
171 :     * comparator, if <tt>fromElement</tt> does not implement
172 :     * <tt>Comparable</tt>).
173 :     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
174 : dl 1.2 * and this set does not permit <tt>null</tt> elements
175 : dl 1.1 */
176 : dl 1.3 NavigableSet<E> navigableTailSet(E fromElement);
177 : dl 1.1 }

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8