1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/compact/src/main/java/java/util/NavigableSet.java Sat Sep 07 13:51:24 2013 +0200
1.3 @@ -0,0 +1,319 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea and Josh Bloch with assistance from members of JCP
1.35 + * JSR-166 Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util;
1.40 +
1.41 +/**
1.42 + * A {@link SortedSet} extended with navigation methods reporting
1.43 + * closest matches for given search targets. Methods {@code lower},
1.44 + * {@code floor}, {@code ceiling}, and {@code higher} return elements
1.45 + * respectively less than, less than or equal, greater than or equal,
1.46 + * and greater than a given element, returning {@code null} if there
1.47 + * is no such element. A {@code NavigableSet} may be accessed and
1.48 + * traversed in either ascending or descending order. The {@code
1.49 + * descendingSet} method returns a view of the set with the senses of
1.50 + * all relational and directional methods inverted. The performance of
1.51 + * ascending operations and views is likely to be faster than that of
1.52 + * descending ones. This interface additionally defines methods
1.53 + * {@code pollFirst} and {@code pollLast} that return and remove the
1.54 + * lowest and highest element, if one exists, else returning {@code
1.55 + * null}. Methods {@code subSet}, {@code headSet},
1.56 + * and {@code tailSet} differ from the like-named {@code
1.57 + * SortedSet} methods in accepting additional arguments describing
1.58 + * whether lower and upper bounds are inclusive versus exclusive.
1.59 + * Subsets of any {@code NavigableSet} must implement the {@code
1.60 + * NavigableSet} interface.
1.61 + *
1.62 + * <p> The return values of navigation methods may be ambiguous in
1.63 + * implementations that permit {@code null} elements. However, even
1.64 + * in this case the result can be disambiguated by checking
1.65 + * {@code contains(null)}. To avoid such issues, implementations of
1.66 + * this interface are encouraged to <em>not</em> permit insertion of
1.67 + * {@code null} elements. (Note that sorted sets of {@link
1.68 + * Comparable} elements intrinsically do not permit {@code null}.)
1.69 + *
1.70 + * <p>Methods
1.71 + * {@link #subSet(Object, Object) subSet(E, E)},
1.72 + * {@link #headSet(Object) headSet(E)}, and
1.73 + * {@link #tailSet(Object) tailSet(E)}
1.74 + * are specified to return {@code SortedSet} to allow existing
1.75 + * implementations of {@code SortedSet} to be compatibly retrofitted to
1.76 + * implement {@code NavigableSet}, but extensions and implementations
1.77 + * of this interface are encouraged to override these methods to return
1.78 + * {@code NavigableSet}.
1.79 + *
1.80 + * <p>This interface is a member of the
1.81 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
1.82 + * Java Collections Framework</a>.
1.83 + *
1.84 + * @author Doug Lea
1.85 + * @author Josh Bloch
1.86 + * @param <E> the type of elements maintained by this set
1.87 + * @since 1.6
1.88 + */
1.89 +public interface NavigableSet<E> extends SortedSet<E> {
1.90 + /**
1.91 + * Returns the greatest element in this set strictly less than the
1.92 + * given element, or {@code null} if there is no such element.
1.93 + *
1.94 + * @param e the value to match
1.95 + * @return the greatest element less than {@code e},
1.96 + * or {@code null} if there is no such element
1.97 + * @throws ClassCastException if the specified element cannot be
1.98 + * compared with the elements currently in the set
1.99 + * @throws NullPointerException if the specified element is null
1.100 + * and this set does not permit null elements
1.101 + */
1.102 + E lower(E e);
1.103 +
1.104 + /**
1.105 + * Returns the greatest element in this set less than or equal to
1.106 + * the given element, or {@code null} if there is no such element.
1.107 + *
1.108 + * @param e the value to match
1.109 + * @return the greatest element less than or equal to {@code e},
1.110 + * or {@code null} if there is no such element
1.111 + * @throws ClassCastException if the specified element cannot be
1.112 + * compared with the elements currently in the set
1.113 + * @throws NullPointerException if the specified element is null
1.114 + * and this set does not permit null elements
1.115 + */
1.116 + E floor(E e);
1.117 +
1.118 + /**
1.119 + * Returns the least element in this set greater than or equal to
1.120 + * the given element, or {@code null} if there is no such element.
1.121 + *
1.122 + * @param e the value to match
1.123 + * @return the least element greater than or equal to {@code e},
1.124 + * or {@code null} if there is no such element
1.125 + * @throws ClassCastException if the specified element cannot be
1.126 + * compared with the elements currently in the set
1.127 + * @throws NullPointerException if the specified element is null
1.128 + * and this set does not permit null elements
1.129 + */
1.130 + E ceiling(E e);
1.131 +
1.132 + /**
1.133 + * Returns the least element in this set strictly greater than the
1.134 + * given element, or {@code null} if there is no such element.
1.135 + *
1.136 + * @param e the value to match
1.137 + * @return the least element greater than {@code e},
1.138 + * or {@code null} if there is no such element
1.139 + * @throws ClassCastException if the specified element cannot be
1.140 + * compared with the elements currently in the set
1.141 + * @throws NullPointerException if the specified element is null
1.142 + * and this set does not permit null elements
1.143 + */
1.144 + E higher(E e);
1.145 +
1.146 + /**
1.147 + * Retrieves and removes the first (lowest) element,
1.148 + * or returns {@code null} if this set is empty.
1.149 + *
1.150 + * @return the first element, or {@code null} if this set is empty
1.151 + */
1.152 + E pollFirst();
1.153 +
1.154 + /**
1.155 + * Retrieves and removes the last (highest) element,
1.156 + * or returns {@code null} if this set is empty.
1.157 + *
1.158 + * @return the last element, or {@code null} if this set is empty
1.159 + */
1.160 + E pollLast();
1.161 +
1.162 + /**
1.163 + * Returns an iterator over the elements in this set, in ascending order.
1.164 + *
1.165 + * @return an iterator over the elements in this set, in ascending order
1.166 + */
1.167 + Iterator<E> iterator();
1.168 +
1.169 + /**
1.170 + * Returns a reverse order view of the elements contained in this set.
1.171 + * The descending set is backed by this set, so changes to the set are
1.172 + * reflected in the descending set, and vice-versa. If either set is
1.173 + * modified while an iteration over either set is in progress (except
1.174 + * through the iterator's own {@code remove} operation), the results of
1.175 + * the iteration are undefined.
1.176 + *
1.177 + * <p>The returned set has an ordering equivalent to
1.178 + * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
1.179 + * The expression {@code s.descendingSet().descendingSet()} returns a
1.180 + * view of {@code s} essentially equivalent to {@code s}.
1.181 + *
1.182 + * @return a reverse order view of this set
1.183 + */
1.184 + NavigableSet<E> descendingSet();
1.185 +
1.186 + /**
1.187 + * Returns an iterator over the elements in this set, in descending order.
1.188 + * Equivalent in effect to {@code descendingSet().iterator()}.
1.189 + *
1.190 + * @return an iterator over the elements in this set, in descending order
1.191 + */
1.192 + Iterator<E> descendingIterator();
1.193 +
1.194 + /**
1.195 + * Returns a view of the portion of this set whose elements range from
1.196 + * {@code fromElement} to {@code toElement}. If {@code fromElement} and
1.197 + * {@code toElement} are equal, the returned set is empty unless {@code
1.198 + * fromInclusive} and {@code toInclusive} are both true. The returned set
1.199 + * is backed by this set, so changes in the returned set are reflected in
1.200 + * this set, and vice-versa. The returned set supports all optional set
1.201 + * operations that this set supports.
1.202 + *
1.203 + * <p>The returned set will throw an {@code IllegalArgumentException}
1.204 + * on an attempt to insert an element outside its range.
1.205 + *
1.206 + * @param fromElement low endpoint of the returned set
1.207 + * @param fromInclusive {@code true} if the low endpoint
1.208 + * is to be included in the returned view
1.209 + * @param toElement high endpoint of the returned set
1.210 + * @param toInclusive {@code true} if the high endpoint
1.211 + * is to be included in the returned view
1.212 + * @return a view of the portion of this set whose elements range from
1.213 + * {@code fromElement}, inclusive, to {@code toElement}, exclusive
1.214 + * @throws ClassCastException if {@code fromElement} and
1.215 + * {@code toElement} cannot be compared to one another using this
1.216 + * set's comparator (or, if the set has no comparator, using
1.217 + * natural ordering). Implementations may, but are not required
1.218 + * to, throw this exception if {@code fromElement} or
1.219 + * {@code toElement} cannot be compared to elements currently in
1.220 + * the set.
1.221 + * @throws NullPointerException if {@code fromElement} or
1.222 + * {@code toElement} is null and this set does
1.223 + * not permit null elements
1.224 + * @throws IllegalArgumentException if {@code fromElement} is
1.225 + * greater than {@code toElement}; or if this set itself
1.226 + * has a restricted range, and {@code fromElement} or
1.227 + * {@code toElement} lies outside the bounds of the range.
1.228 + */
1.229 + NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
1.230 + E toElement, boolean toInclusive);
1.231 +
1.232 + /**
1.233 + * Returns a view of the portion of this set whose elements are less than
1.234 + * (or equal to, if {@code inclusive} is true) {@code toElement}. The
1.235 + * returned set is backed by this set, so changes in the returned set are
1.236 + * reflected in this set, and vice-versa. The returned set supports all
1.237 + * optional set operations that this set supports.
1.238 + *
1.239 + * <p>The returned set will throw an {@code IllegalArgumentException}
1.240 + * on an attempt to insert an element outside its range.
1.241 + *
1.242 + * @param toElement high endpoint of the returned set
1.243 + * @param inclusive {@code true} if the high endpoint
1.244 + * is to be included in the returned view
1.245 + * @return a view of the portion of this set whose elements are less than
1.246 + * (or equal to, if {@code inclusive} is true) {@code toElement}
1.247 + * @throws ClassCastException if {@code toElement} is not compatible
1.248 + * with this set's comparator (or, if the set has no comparator,
1.249 + * if {@code toElement} does not implement {@link Comparable}).
1.250 + * Implementations may, but are not required to, throw this
1.251 + * exception if {@code toElement} cannot be compared to elements
1.252 + * currently in the set.
1.253 + * @throws NullPointerException if {@code toElement} is null and
1.254 + * this set does not permit null elements
1.255 + * @throws IllegalArgumentException if this set itself has a
1.256 + * restricted range, and {@code toElement} lies outside the
1.257 + * bounds of the range
1.258 + */
1.259 + NavigableSet<E> headSet(E toElement, boolean inclusive);
1.260 +
1.261 + /**
1.262 + * Returns a view of the portion of this set whose elements are greater
1.263 + * than (or equal to, if {@code inclusive} is true) {@code fromElement}.
1.264 + * The returned set is backed by this set, so changes in the returned set
1.265 + * are reflected in this set, and vice-versa. The returned set supports
1.266 + * all optional set operations that this set supports.
1.267 + *
1.268 + * <p>The returned set will throw an {@code IllegalArgumentException}
1.269 + * on an attempt to insert an element outside its range.
1.270 + *
1.271 + * @param fromElement low endpoint of the returned set
1.272 + * @param inclusive {@code true} if the low endpoint
1.273 + * is to be included in the returned view
1.274 + * @return a view of the portion of this set whose elements are greater
1.275 + * than or equal to {@code fromElement}
1.276 + * @throws ClassCastException if {@code fromElement} is not compatible
1.277 + * with this set's comparator (or, if the set has no comparator,
1.278 + * if {@code fromElement} does not implement {@link Comparable}).
1.279 + * Implementations may, but are not required to, throw this
1.280 + * exception if {@code fromElement} cannot be compared to elements
1.281 + * currently in the set.
1.282 + * @throws NullPointerException if {@code fromElement} is null
1.283 + * and this set does not permit null elements
1.284 + * @throws IllegalArgumentException if this set itself has a
1.285 + * restricted range, and {@code fromElement} lies outside the
1.286 + * bounds of the range
1.287 + */
1.288 + NavigableSet<E> tailSet(E fromElement, boolean inclusive);
1.289 +
1.290 + /**
1.291 + * {@inheritDoc}
1.292 + *
1.293 + * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
1.294 + *
1.295 + * @throws ClassCastException {@inheritDoc}
1.296 + * @throws NullPointerException {@inheritDoc}
1.297 + * @throws IllegalArgumentException {@inheritDoc}
1.298 + */
1.299 + SortedSet<E> subSet(E fromElement, E toElement);
1.300 +
1.301 + /**
1.302 + * {@inheritDoc}
1.303 + *
1.304 + * <p>Equivalent to {@code headSet(toElement, false)}.
1.305 + *
1.306 + * @throws ClassCastException {@inheritDoc}
1.307 + * @throws NullPointerException {@inheritDoc}
1.308 + * @throws IllegalArgumentException {@inheritDoc}
1.309 +na */
1.310 + SortedSet<E> headSet(E toElement);
1.311 +
1.312 + /**
1.313 + * {@inheritDoc}
1.314 + *
1.315 + * <p>Equivalent to {@code tailSet(fromElement, true)}.
1.316 + *
1.317 + * @throws ClassCastException {@inheritDoc}
1.318 + * @throws NullPointerException {@inheritDoc}
1.319 + * @throws IllegalArgumentException {@inheritDoc}
1.320 + */
1.321 + SortedSet<E> tailSet(E fromElement);
1.322 +}