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

# 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     */
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 dl 1.2 * and this set does not permit <tt>null</tt> elements
52 dl 1.1 */
53 dl 1.3 E ceiling(E o);
54 dl 1.1
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 dl 1.2 * and this set does not permit <tt>null</tt> elements
66 dl 1.1 */
67 dl 1.3 E lower(E o);
68 dl 1.1
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 dl 1.2 * and this set does not permit <tt>null</tt> elements
80 dl 1.1 */
81 dl 1.3 E floor(E o);
82 dl 1.1
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 dl 1.2 * and this set does not permit <tt>null</tt> elements
94 dl 1.1 */
95 dl 1.3 E higher(E o);
96 dl 1.1
97     /**
98     * Retrieves and removes the first (lowest) element.
99     *
100     * @return the first element, or <tt>null</tt> if empty.
101     */
102 dl 1.3 E pollFirst();
103 dl 1.1
104     /**
105     * Retrieves and removes the last (highest) element.
106     *
107     * @return the last element, or <tt>null</tt> if empty.
108     */
109 dl 1.3 E pollLast();
110 dl 1.1
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 dl 1.3 * 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 dl 1.4 * navigable set are reflected in this set, and vice-versa.
126 dl 1.3 *
127 dl 1.1 * @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 dl 1.2 * and this set does not permit <tt>null</tt> elements
141 dl 1.1 */
142 dl 1.3 NavigableSet<E> navigableSubSet(E fromElement, E toElement);
143 dl 1.1
144     /**
145 dl 1.3 * 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 dl 1.1 * @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 dl 1.2 * and this set does not permit <tt>null</tt> elements
157 dl 1.1 */
158 dl 1.3 NavigableSet<E> navigableHeadSet(E toElement);
159 dl 1.1
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 dl 1.3 * navigable set is backed by this set, so changes in the returned
164     * navigable set are reflected in this set, and vice-versa.
165 dl 1.1 * @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 dl 1.2 * and this set does not permit <tt>null</tt> elements
174 dl 1.1 */
175 dl 1.3 NavigableSet<E> navigableTailSet(E fromElement);
176 dl 1.1 }