ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/NavigableSet.java
Revision: 1.7
Committed: Mon May 2 22:34:56 2005 UTC (19 years, 1 month ago) by jsr166
Branch: MAIN
Changes since 1.6: +1 -0 lines
Log Message: 
Add missing @since 1.6

File Contents

# User Rev Content
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 }