151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This file is available under and governed by the GNU General Public 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * License version 2 only, as published by the Free Software Foundation. 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * However, the following notice accompanied the original version of this 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file: 30242e5bfd7e912be174c03a3c887369a6a9d6cbc2Tobias Thierer * 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Written by Doug Lea and Josh Bloch with assistance from members of JCP 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * JSR-166 Expert Group and released to the public domain, as explained at 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * http://creativecommons.org/publicdomain/zero/1.0/ 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 36fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller// BEGIN android-note 37fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller// removed link to collections framework docs 38fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller// END android-note 39fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller 40b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniakpackage java.util; 41b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A {@link SortedSet} extended with navigation methods reporting 44b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * closest matches for given search targets. Methods {@link #lower}, 45b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * respectively less than, less than or equal, greater than or equal, 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and greater than a given element, returning {@code null} if there 48b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * is no such element. 49b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * 50b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * <p>A {@code NavigableSet} may be accessed and traversed in either 51b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * ascending or descending order. The {@link #descendingSet} method 52b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * returns a view of the set with the senses of all relational and 53b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * directional methods inverted. The performance of ascending 54b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * operations and views is likely to be faster than that of descending 55b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * ones. This interface additionally defines methods {@link 56b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * #pollFirst} and {@link #pollLast} that return and remove the lowest 57b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * and highest element, if one exists, else returning {@code null}. 58b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * Methods 59b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * {@link #subSet(Object, boolean, Object, boolean) subSet(E, boolean, E, boolean)}, 60b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * {@link #headSet(Object, boolean) headSet(E, boolean)}, and 61b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * {@link #tailSet(Object, boolean) tailSet(E, boolean)} 62b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * differ from the like-named {@code SortedSet} methods in accepting 63b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * additional arguments describing whether lower and upper bounds are 64b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * inclusive versus exclusive. Subsets of any {@code NavigableSet} 65b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * must implement the {@code NavigableSet} interface. 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 67fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller * <p>The return values of navigation methods may be ambiguous in 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * implementations that permit {@code null} elements. However, even 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in this case the result can be disambiguated by checking 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code contains(null)}. To avoid such issues, implementations of 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this interface are encouraged to <em>not</em> permit insertion of 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code null} elements. (Note that sorted sets of {@link 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Comparable} elements intrinsically do not permit {@code null}.) 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Methods 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #subSet(Object, Object) subSet(E, E)}, 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #headSet(Object) headSet(E)}, and 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #tailSet(Object) tailSet(E)} 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are specified to return {@code SortedSet} to allow existing 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * implementations of {@code SortedSet} to be compatibly retrofitted to 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * implement {@code NavigableSet}, but extensions and implementations 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of this interface are encouraged to override these methods to return 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code NavigableSet}. 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Doug Lea 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Josh Bloch 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param <E> the type of elements maintained by this set 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.6 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic interface NavigableSet<E> extends SortedSet<E> { 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the greatest element in this set strictly less than the 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given element, or {@code null} if there is no such element. 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param e the value to match 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the greatest element less than {@code e}, 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or {@code null} if there is no such element 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if the specified element cannot be 9951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * compared with the elements currently in the set 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if the specified element is null 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and this set does not permit null elements 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E lower(E e); 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the greatest element in this set less than or equal to 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the given element, or {@code null} if there is no such element. 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param e the value to match 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the greatest element less than or equal to {@code e}, 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or {@code null} if there is no such element 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if the specified element cannot be 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * compared with the elements currently in the set 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if the specified element is null 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and this set does not permit null elements 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E floor(E e); 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the least element in this set greater than or equal to 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the given element, or {@code null} if there is no such element. 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param e the value to match 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the least element greater than or equal to {@code e}, 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or {@code null} if there is no such element 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if the specified element cannot be 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * compared with the elements currently in the set 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if the specified element is null 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and this set does not permit null elements 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E ceiling(E e); 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the least element in this set strictly greater than the 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given element, or {@code null} if there is no such element. 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param e the value to match 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the least element greater than {@code e}, 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or {@code null} if there is no such element 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if the specified element cannot be 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * compared with the elements currently in the set 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if the specified element is null 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and this set does not permit null elements 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E higher(E e); 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieves and removes the first (lowest) element, 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or returns {@code null} if this set is empty. 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the first element, or {@code null} if this set is empty 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E pollFirst(); 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Retrieves and removes the last (highest) element, 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or returns {@code null} if this set is empty. 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the last element, or {@code null} if this set is empty 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E pollLast(); 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 16451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns an iterator over the elements in this set, in ascending order. 16551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 16651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return an iterator over the elements in this set, in ascending order 16751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski Iterator<E> iterator(); 16951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 17051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 17151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a reverse order view of the elements contained in this set. 17251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The descending set is backed by this set, so changes to the set are 17351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * reflected in the descending set, and vice-versa. If either set is 17451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * modified while an iteration over either set is in progress (except 17551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * through the iterator's own {@code remove} operation), the results of 17651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the iteration are undefined. 17751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 17851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The returned set has an ordering equivalent to 179fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller * {@link Collections#reverseOrder(Comparator) Collections.reverseOrder}{@code (comparator())}. 18051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The expression {@code s.descendingSet().descendingSet()} returns a 18151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * view of {@code s} essentially equivalent to {@code s}. 18251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 18351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a reverse order view of this set 18451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 18551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski NavigableSet<E> descendingSet(); 18651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 18751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 18851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns an iterator over the elements in this set, in descending order. 18951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Equivalent in effect to {@code descendingSet().iterator()}. 19051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 19151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return an iterator over the elements in this set, in descending order 19251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 19351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski Iterator<E> descendingIterator(); 19451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 19551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 19651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a view of the portion of this set whose elements range from 19751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code fromElement} to {@code toElement}. If {@code fromElement} and 19851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code toElement} are equal, the returned set is empty unless {@code 199b8b75116273ecfdb8ffdd1869b1c0dd04570a95ePrzemyslaw Szczepaniak * fromInclusive} and {@code toInclusive} are both true. The returned set 20051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is backed by this set, so changes in the returned set are reflected in 20151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this set, and vice-versa. The returned set supports all optional set 20251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operations that this set supports. 20351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 20451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The returned set will throw an {@code IllegalArgumentException} 20551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on an attempt to insert an element outside its range. 20651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 20751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param fromElement low endpoint of the returned set 20851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param fromInclusive {@code true} if the low endpoint 20951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be included in the returned view 21051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param toElement high endpoint of the returned set 21151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param toInclusive {@code true} if the high endpoint 21251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be included in the returned view 21351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a view of the portion of this set whose elements range from 21451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code fromElement}, inclusive, to {@code toElement}, exclusive 21551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if {@code fromElement} and 21651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code toElement} cannot be compared to one another using this 21751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * set's comparator (or, if the set has no comparator, using 21851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * natural ordering). Implementations may, but are not required 21951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to, throw this exception if {@code fromElement} or 22051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code toElement} cannot be compared to elements currently in 22151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the set. 22251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if {@code fromElement} or 22351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code toElement} is null and this set does 22451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * not permit null elements 22551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException if {@code fromElement} is 22651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * greater than {@code toElement}; or if this set itself 22751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * has a restricted range, and {@code fromElement} or 22851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@code toElement} lies outside the bounds of the range. 22951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 23051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski NavigableSet<E> subSet(E fromElement, boolean fromInclusive, 23151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski E toElement, boolean toInclusive); 23251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 23351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 23451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a view of the portion of this set whose elements are less than 23551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (or equal to, if {@code inclusive} is true) {@code toElement}. The 23651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returned set is backed by this set, so changes in the returned set are 23751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * reflected in this set, and vice-versa. The returned set supports all 23851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * optional set operations that this set supports. 23951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 24051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The returned set will throw an {@code IllegalArgumentException} 24151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on an attempt to insert an element outside its range. 24251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 24351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param toElement high endpoint of the returned set 24451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param inclusive {@code true} if the high endpoint 24551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be included in the returned view 24651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a view of the portion of this set whose elements are less than 24751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (or equal to, if {@code inclusive} is true) {@code toElement} 24851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if {@code toElement} is not compatible 24951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with this set's comparator (or, if the set has no comparator, 25051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if {@code toElement} does not implement {@link Comparable}). 25151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Implementations may, but are not required to, throw this 25251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * exception if {@code toElement} cannot be compared to elements 25351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * currently in the set. 25451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if {@code toElement} is null and 25551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this set does not permit null elements 25651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException if this set itself has a 25751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * restricted range, and {@code toElement} lies outside the 25851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * bounds of the range 25951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 26051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski NavigableSet<E> headSet(E toElement, boolean inclusive); 26151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 26251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 26351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a view of the portion of this set whose elements are greater 26451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * than (or equal to, if {@code inclusive} is true) {@code fromElement}. 26551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The returned set is backed by this set, so changes in the returned set 26651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are reflected in this set, and vice-versa. The returned set supports 26751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * all optional set operations that this set supports. 26851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 26951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The returned set will throw an {@code IllegalArgumentException} 27051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on an attempt to insert an element outside its range. 27151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 27251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param fromElement low endpoint of the returned set 27351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param inclusive {@code true} if the low endpoint 27451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to be included in the returned view 27551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a view of the portion of this set whose elements are greater 27651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * than or equal to {@code fromElement} 27751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException if {@code fromElement} is not compatible 27851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with this set's comparator (or, if the set has no comparator, 27951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if {@code fromElement} does not implement {@link Comparable}). 28051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Implementations may, but are not required to, throw this 28151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * exception if {@code fromElement} cannot be compared to elements 28251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * currently in the set. 28351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException if {@code fromElement} is null 28451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and this set does not permit null elements 28551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException if this set itself has a 28651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * restricted range, and {@code fromElement} lies outside the 28751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * bounds of the range 28851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 28951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski NavigableSet<E> tailSet(E fromElement, boolean inclusive); 29051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 29151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 29251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@inheritDoc} 29351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 29451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}. 29551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 29651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException {@inheritDoc} 29751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException {@inheritDoc} 29851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException {@inheritDoc} 29951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 30051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski SortedSet<E> subSet(E fromElement, E toElement); 30151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 30251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 30351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@inheritDoc} 30451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 30551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Equivalent to {@code headSet(toElement, false)}. 30651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 30751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException {@inheritDoc} 30851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException {@inheritDoc} 30951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException {@inheritDoc} 310fd81a99407d318ea3d8b5782294a0644e580d126Neil Fuller */ 31151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski SortedSet<E> headSet(E toElement); 31251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 31351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 31451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@inheritDoc} 31551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 31651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>Equivalent to {@code tailSet(fromElement, true)}. 31751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 31851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClassCastException {@inheritDoc} 31951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NullPointerException {@inheritDoc} 32051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException {@inheritDoc} 32151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 32251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski SortedSet<E> tailSet(E fromElement); 32351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 324