Java tutorial
/* * Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.util; /** * A {@link Set} that further provides a <i>total ordering</i> on its elements. * The elements are ordered using their {@linkplain Comparable natural * ordering}, or by a {@link Comparator} typically provided at sorted * set creation time. The set's iterator will traverse the set in * ascending element order. Several additional operations are provided * to take advantage of the ordering. (This interface is the set * analogue of {@link SortedMap}.) * * <p>All elements inserted into a sorted set must implement the {@code Comparable} * interface (or be accepted by the specified comparator). Furthermore, all * such elements must be <i>mutually comparable</i>: {@code e1.compareTo(e2)} * (or {@code comparator.compare(e1, e2)}) must not throw a * {@code ClassCastException} for any elements {@code e1} and {@code e2} in * the sorted set. Attempts to violate this restriction will cause the * offending method or constructor invocation to throw a * {@code ClassCastException}. * * <p>Note that the ordering maintained by a sorted set (whether or not an * explicit comparator is provided) must be <i>consistent with equals</i> if * the sorted set is to correctly implement the {@code Set} interface. (See * the {@code Comparable} interface or {@code Comparator} interface for a * precise definition of <i>consistent with equals</i>.) This is so because * the {@code Set} interface is defined in terms of the {@code equals} * operation, but a sorted set performs all element comparisons using its * {@code compareTo} (or {@code compare}) method, so two elements that are * deemed equal by this method are, from the standpoint of the sorted set, * equal. The behavior of a sorted set <i>is</i> well-defined even if its * ordering is inconsistent with equals; it just fails to obey the general * contract of the {@code Set} interface. * * <p>All general-purpose sorted set implementation classes should * provide four "standard" constructors: 1) A void (no arguments) * constructor, which creates an empty sorted set sorted according to * the natural ordering of its elements. 2) A constructor with a * single argument of type {@code Comparator}, which creates an empty * sorted set sorted according to the specified comparator. 3) A * constructor with a single argument of type {@code Collection}, * which creates a new sorted set with the same elements as its * argument, sorted according to the natural ordering of the elements. * 4) A constructor with a single argument of type {@code SortedSet}, * which creates a new sorted set with the same elements and the same * ordering as the input sorted set. There is no way to enforce this * recommendation, as interfaces cannot contain constructors. * * <p>Note: several methods return subsets with restricted ranges. * Such ranges are <i>half-open</i>, that is, they include their low * endpoint but not their high endpoint (where applicable). * If you need a <i>closed range</i> (which includes both endpoints), and * the element type allows for calculation of the successor of a given * value, merely request the subrange from {@code lowEndpoint} to * {@code successor(highEndpoint)}. For example, suppose that {@code s} * is a sorted set of strings. The following idiom obtains a view * containing all of the strings in {@code s} from {@code low} to * {@code high}, inclusive:<pre> * SortedSet<String> sub = s.subSet(low, high+"\0");</pre> * * A similar technique can be used to generate an <i>open range</i> (which * contains neither endpoint). The following idiom obtains a view * containing all of the Strings in {@code s} from {@code low} to * {@code high}, exclusive:<pre> * SortedSet<String> sub = s.subSet(low+"\0", high);</pre> * * <p>This interface is a member of the * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework"> * Java Collections Framework</a>. * * @param <E> the type of elements maintained by this set * * @author Josh Bloch * @see Set * @see TreeSet * @see SortedMap * @see Collection * @see Comparable * @see Comparator * @see ClassCastException * @since 1.2 */ public interface SortedSet<E> extends Set<E> { /** * Returns the comparator used to order the elements in this set, * or {@code null} if this set uses the {@linkplain Comparable * natural ordering} of its elements. * * @return the comparator used to order the elements in this set, * or {@code null} if this set uses the natural ordering * of its elements */ Comparator<? super E> comparator(); /** * Returns a view of the portion of this set whose elements range * from {@code fromElement}, inclusive, to {@code toElement}, * exclusive. (If {@code fromElement} and {@code toElement} are * equal, the returned set is empty.) The returned set is backed * by this set, so changes in the returned set are reflected in * this set, and vice-versa. The returned set supports all * optional set operations that this set supports. * * <p>The returned set will throw an {@code IllegalArgumentException} * on an attempt to insert an element outside its range. * * @param fromElement low endpoint (inclusive) of the returned set * @param toElement high endpoint (exclusive) of the returned set * @return a view of the portion of this set whose elements range from * {@code fromElement}, inclusive, to {@code toElement}, exclusive * @throws ClassCastException if {@code fromElement} and * {@code toElement} cannot be compared to one another using this * set's comparator (or, if the set has no comparator, using * natural ordering). Implementations may, but are not required * to, throw this exception if {@code fromElement} or * {@code toElement} cannot be compared to elements currently in * the set. * @throws NullPointerException if {@code fromElement} or * {@code toElement} is null and this set does not permit null * elements * @throws IllegalArgumentException if {@code fromElement} is * greater than {@code toElement}; or if this set itself * has a restricted range, and {@code fromElement} or * {@code toElement} lies outside the bounds of the range */ SortedSet<E> subSet(E fromElement, E toElement); /** * Returns a view of the portion of this set whose elements are * strictly less than {@code toElement}. The returned set is * backed by this set, so changes in the returned set are * reflected in this set, and vice-versa. The returned set * supports all optional set operations that this set supports. * * <p>The returned set will throw an {@code IllegalArgumentException} * on an attempt to insert an element outside its range. * * @param toElement high endpoint (exclusive) of the returned set * @return a view of the portion of this set whose elements are strictly * less than {@code toElement} * @throws ClassCastException if {@code toElement} is not compatible * with this set's comparator (or, if the set has no comparator, * if {@code toElement} does not implement {@link Comparable}). * Implementations may, but are not required to, throw this * exception if {@code toElement} cannot be compared to elements * currently in the set. * @throws NullPointerException if {@code toElement} is null and * this set does not permit null elements * @throws IllegalArgumentException if this set itself has a * restricted range, and {@code toElement} lies outside the * bounds of the range */ SortedSet<E> headSet(E toElement); /** * Returns a view of the portion of this set whose elements are * greater than or equal to {@code fromElement}. The returned * set is backed by this set, so changes in the returned set are * reflected in this set, and vice-versa. The returned set * supports all optional set operations that this set supports. * * <p>The returned set will throw an {@code IllegalArgumentException} * on an attempt to insert an element outside its range. * * @param fromElement low endpoint (inclusive) of the returned set * @return a view of the portion of this set whose elements are greater * than or equal to {@code fromElement} * @throws ClassCastException if {@code fromElement} is not compatible * with this set's comparator (or, if the set has no comparator, * if {@code fromElement} does not implement {@link Comparable}). * Implementations may, but are not required to, throw this * exception if {@code fromElement} cannot be compared to elements * currently in the set. * @throws NullPointerException if {@code fromElement} is null * and this set does not permit null elements * @throws IllegalArgumentException if this set itself has a * restricted range, and {@code fromElement} lies outside the * bounds of the range */ SortedSet<E> tailSet(E fromElement); /** * Returns the first (lowest) element currently in this set. * * @return the first (lowest) element currently in this set * @throws NoSuchElementException if this set is empty */ E first(); /** * Returns the last (highest) element currently in this set. * * @return the last (highest) element currently in this set * @throws NoSuchElementException if this set is empty */ E last(); /** * Creates a {@code Spliterator} over the elements in this sorted set. * * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT}, * {@link Spliterator#SORTED} and {@link Spliterator#ORDERED}. * Implementations should document the reporting of additional * characteristic values. * * <p>The spliterator's comparator (see * {@link java.util.Spliterator#getComparator()}) must be {@code null} if * the sorted set's comparator (see {@link #comparator()}) is {@code null}. * Otherwise, the spliterator's comparator must be the same as or impose the * same total ordering as the sorted set's comparator. * * @implSpec * The default implementation creates a * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator * from the sorted set's {@code Iterator}. The spliterator inherits the * <em>fail-fast</em> properties of the set's iterator. The * spliterator's comparator is the same as the sorted set's comparator. * <p> * The created {@code Spliterator} additionally reports * {@link Spliterator#SIZED}. * * @implNote * The created {@code Spliterator} additionally reports * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this sorted set * @since 1.8 */ @Override default Spliterator<E> spliterator() { return new Spliterators.IteratorSpliterator<E>(this, Spliterator.DISTINCT | Spliterator.SORTED | Spliterator.ORDERED) { @Override public Comparator<? super E> getComparator() { return SortedSet.this.comparator(); } }; } }