001: package j2me.util;
002:
003: /*
004: * Written by Doug Lea and Josh Bloch with assistance from members of JCP
005: * JSR-166 Expert Group and released to the public domain, as explained at
006: * http://creativecommons.org/licenses/publicdomain
007: */
008:
009: import j2me.util.SortedSet;
010: import j2me.util.Iterator;
011:
012: /**
013: * A {@link java.util.SortedSet} extended with navigation methods reporting
014: * closest matches for given search targets. Methods {@code lower},
015: * {@code floor}, {@code ceiling}, and {@code higher} return elements
016: * respectively less than, less than or equal, greater than or equal,
017: * and greater than a given element, returning {@code null} if there
018: * is no such element. A {@code NavigableSet} may be accessed and
019: * traversed in either ascending or descending order. The {@code
020: * descendingSet} method returns a view of the set with the senses of
021: * all relational and directional methods inverted. The performance of
022: * ascending operations and views is likely to be faster than that of
023: * descending ones. This interface additionally defines methods
024: * {@code pollFirst} and {@code pollLast} that return and remove the
025: * lowest and highest element, if one exists, else returning {@code
026: * null}. Methods {@code subSet}, {@code headSet},
027: * and {@code tailSet} differ from the like-named {@code
028: * SortedSet} methods in accepting additional arguments describing
029: * whether lower and upper bounds are inclusive versus exclusive.
030: * Subsets of any {@code NavigableSet} must implement the {@code
031: * NavigableSet} interface.
032: *
033: * <p> The return values of navigation methods may be ambiguous in
034: * implementations that permit {@code null} elements. However, even
035: * in this case the result can be disambiguated by checking
036: * {@code contains(null)}. To avoid such issues, implementations of
037: * this interface are encouraged to <em>not</em> permit insertion of
038: * {@code null} elements. (Note that sorted sets of {@link
039: * java.lang.Comparable} elements intrinsically do not permit {@code null}.)
040: *
041: * <p>Methods
042: * {@link #subSet(Object, Object) subSet(E, E)},
043: * {@link #headSet(Object) headSet(E)}, and
044: * {@link #tailSet(Object) tailSet(E)}
045: * are specified to return {@code SortedSet} to allow existing
046: * implementations of {@code SortedSet} to be compatibly retrofitted to
047: * implement {@code NavigableSet}, but extensions and implementations
048: * of this interface are encouraged to override these methods to return
049: * {@code NavigableSet}.
050: *
051: * <p>This interface is a member of the
052: * <a href="{@docRoot}/../technotes/guides/collections/index.html">
053: * Java Collections Framework</a>.
054: *
055: * @author Doug Lea
056: * @author Josh Bloch
057: * @since 1.6
058: */
059: public interface NavigableSet extends SortedSet {
060: /**
061: * Returns the greatest element in this set strictly less than the
062: * given element, or {@code null} if there is no such element.
063: *
064: * @param e the value to match
065: * @return the greatest element less than {@code e},
066: * or {@code null} if there is no such element
067: * @throws ClassCastException if the specified element cannot be
068: * compared with the elements currently in the set
069: * @throws NullPointerException if the specified element is null
070: * and this set does not permit null elements
071: */
072: Object lower(Object e);
073:
074: /**
075: * Returns the greatest element in this set less than or equal to
076: * the given element, or {@code null} if there is no such element.
077: *
078: * @param e the value to match
079: * @return the greatest element less than or equal to {@code e},
080: * or {@code null} if there is no such element
081: * @throws ClassCastException if the specified element cannot be
082: * compared with the elements currently in the set
083: * @throws NullPointerException if the specified element is null
084: * and this set does not permit null elements
085: */
086: Object floor(Object e);
087:
088: /**
089: * Returns the least element in this set greater than or equal to
090: * the given element, or {@code null} if there is no such element.
091: *
092: * @param e the value to match
093: * @return the least element greater than or equal to {@code e},
094: * or {@code null} if there is no such element
095: * @throws ClassCastException if the specified element cannot be
096: * compared with the elements currently in the set
097: * @throws NullPointerException if the specified element is null
098: * and this set does not permit null elements
099: */
100: Object ceiling(Object e);
101:
102: /**
103: * Returns the least element in this set strictly greater than the
104: * given element, or {@code null} if there is no such element.
105: *
106: * @param e the value to match
107: * @return the least element greater than {@code e},
108: * or {@code null} if there is no such element
109: * @throws ClassCastException if the specified element cannot be
110: * compared with the elements currently in the set
111: * @throws NullPointerException if the specified element is null
112: * and this set does not permit null elements
113: */
114: Object higher(Object e);
115:
116: /**
117: * Retrieves and removes the first (lowest) element,
118: * or returns {@code null} if this set is empty.
119: *
120: * @return the first element, or {@code null} if this set is empty
121: */
122: Object pollFirst();
123:
124: /**
125: * Retrieves and removes the last (highest) element,
126: * or returns {@code null} if this set is empty.
127: *
128: * @return the last element, or {@code null} if this set is empty
129: */
130: Object pollLast();
131:
132: /**
133: * Returns an iterator over the elements in this set, in ascending order.
134: *
135: * @return an iterator over the elements in this set, in ascending order
136: */
137: Iterator iterator();
138:
139: /**
140: * Returns a reverse order view of the elements contained in this set.
141: * The descending set is backed by this set, so changes to the set are
142: * reflected in the descending set, and vice-versa. If either set is
143: * modified while an iteration over either set is in progress (except
144: * through the iterator's own {@code remove} operation), the results of
145: * the iteration are undefined.
146: *
147: * <p>The returned set has an ordering equivalent to
148: * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
149: * The expression {@code s.descendingSet().descendingSet()} returns a
150: * view of {@code s} essentially equivalent to {@code s}.
151: *
152: * @return a reverse order view of this set
153: */
154: NavigableSet descendingSet();
155:
156: /**
157: * Returns an iterator over the elements in this set, in descending order.
158: * Equivalent in effect to {@code descendingSet().iterator()}.
159: *
160: * @return an iterator over the elements in this set, in descending order
161: */
162: Iterator descendingIterator();
163:
164: /**
165: * Returns a view of the portion of this set whose elements range from
166: * {@code fromElement} to {@code toElement}. If {@code fromElement} and
167: * {@code toElement} are equal, the returned set is empty unless {@code
168: * fromExclusive} and {@code toExclusive} are both true. The returned set
169: * is backed by this set, so changes in the returned set are reflected in
170: * this set, and vice-versa. The returned set supports all optional set
171: * operations that this set supports.
172: *
173: * <p>The returned set will throw an {@code IllegalArgumentException}
174: * on an attempt to insert an element outside its range.
175: *
176: * @param fromElement low endpoint of the returned set
177: * @param fromInclusive {@code true} if the low endpoint
178: * is to be included in the returned view
179: * @param toElement high endpoint of the returned set
180: * @param toInclusive {@code true} if the high endpoint
181: * is to be included in the returned view
182: * @return a view of the portion of this set whose elements range from
183: * {@code fromElement}, inclusive, to {@code toElement}, exclusive
184: * @throws ClassCastException if {@code fromElement} and
185: * {@code toElement} cannot be compared to one another using this
186: * set's comparator (or, if the set has no comparator, using
187: * natural ordering). Implementations may, but are not required
188: * to, throw this exception if {@code fromElement} or
189: * {@code toElement} cannot be compared to elements currently in
190: * the set.
191: * @throws NullPointerException if {@code fromElement} or
192: * {@code toElement} is null and this set does
193: * not permit null elements
194: * @throws IllegalArgumentException if {@code fromElement} is
195: * greater than {@code toElement}; or if this set itself
196: * has a restricted range, and {@code fromElement} or
197: * {@code toElement} lies outside the bounds of the range.
198: */
199: NavigableSet subSet(Object fromElement, boolean fromInclusive,
200: Object toElement, boolean toInclusive);
201:
202: /**
203: * Returns a view of the portion of this set whose elements are less than
204: * (or equal to, if {@code inclusive} is true) {@code toElement}. The
205: * returned set is backed by this set, so changes in the returned set are
206: * reflected in this set, and vice-versa. The returned set supports all
207: * optional set operations that this set supports.
208: *
209: * <p>The returned set will throw an {@code IllegalArgumentException}
210: * on an attempt to insert an element outside its range.
211: *
212: * @param toElement high endpoint of the returned set
213: * @param inclusive {@code true} if the high endpoint
214: * is to be included in the returned view
215: * @return a view of the portion of this set whose elements are less than
216: * (or equal to, if {@code inclusive} is true) {@code toElement}
217: * @throws ClassCastException if {@code toElement} is not compatible
218: * with this set's comparator (or, if the set has no comparator,
219: * if {@code toElement} does not implement {@link java.lang.Comparable}).
220: * Implementations may, but are not required to, throw this
221: * exception if {@code toElement} cannot be compared to elements
222: * currently in the set.
223: * @throws NullPointerException if {@code toElement} is null and
224: * this set does not permit null elements
225: * @throws IllegalArgumentException if this set itself has a
226: * restricted range, and {@code toElement} lies outside the
227: * bounds of the range
228: */
229: NavigableSet headSet(Object toElement, boolean inclusive);
230:
231: /**
232: * Returns a view of the portion of this set whose elements are greater
233: * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
234: * The returned set is backed by this set, so changes in the returned set
235: * are reflected in this set, and vice-versa. The returned set supports
236: * all optional set operations that this set supports.
237: *
238: * <p>The returned set will throw an {@code IllegalArgumentException}
239: * on an attempt to insert an element outside its range.
240: *
241: * @param fromElement low endpoint of the returned set
242: * @param inclusive {@code true} if the low endpoint
243: * is to be included in the returned view
244: * @return a view of the portion of this set whose elements are greater
245: * than or equal to {@code fromElement}
246: * @throws ClassCastException if {@code fromElement} is not compatible
247: * with this set's comparator (or, if the set has no comparator,
248: * if {@code fromElement} does not implement {@link java.lang.Comparable}).
249: * Implementations may, but are not required to, throw this
250: * exception if {@code fromElement} cannot be compared to elements
251: * currently in the set.
252: * @throws NullPointerException if {@code fromElement} is null
253: * and this set does not permit null elements
254: * @throws IllegalArgumentException if this set itself has a
255: * restricted range, and {@code fromElement} lies outside the
256: * bounds of the range
257: */
258: NavigableSet tailSet(Object fromElement, boolean inclusive);
259:
260: /**
261: * {@inheritDoc}
262: *
263: * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
264: *
265: * @throws ClassCastException {@inheritDoc}
266: * @throws NullPointerException {@inheritDoc}
267: * @throws IllegalArgumentException {@inheritDoc}
268: */
269: SortedSet subSet(Object fromElement, Object toElement);
270:
271: /**
272: * {@inheritDoc}
273: *
274: * <p>Equivalent to {@code headSet(toElement, false)}.
275: *
276: * @throws ClassCastException {@inheritDoc}
277: * @throws NullPointerException {@inheritDoc}
278: * @throws IllegalArgumentException {@inheritDoc}
279: */
280: SortedSet headSet(Object toElement);
281:
282: /**
283: * {@inheritDoc}
284: *
285: * <p>Equivalent to {@code tailSet(fromElement, true)}.
286: *
287: * @throws ClassCastException {@inheritDoc}
288: * @throws NullPointerException {@inheritDoc}
289: * @throws IllegalArgumentException {@inheritDoc}
290: */
291: SortedSet tailSet(Object fromElement);
292: }
|