ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/NavigableSet.java
Revision: 1.8
Committed: Tue May 3 02:52:07 2005 UTC (19 years, 1 month ago) by jsr166
Branch: MAIN
Changes since 1.7: +4 -0 lines
Log Message: 
Update collections framework pointer

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