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

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8