1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package java.util; 19 20 21 /** 22 * SortedSet is a Set which iterates over its elements in a sorted order. The 23 * order is determined either by the elements natural ordering, or by a 24 * {@link Comparator} which is passed into a concrete implementation at 25 * construction time. All elements in this set must be mutually comparable. The 26 * ordering in this set must be consistent with {@code equals} of its elements. 27 * 28 * @see Comparator 29 * @see Comparable 30 */ 31 public interface SortedSet<E> extends Set<E> { 32 33 /** 34 * Returns the comparator used to compare elements in this {@code SortedSet}. 35 * 36 * @return a comparator or null if the natural ordering is used. 37 */ comparator()38 public Comparator<? super E> comparator(); 39 40 /** 41 * Returns the first element in this {@code SortedSet}. The first element 42 * is the lowest element. 43 * 44 * @return the first element. 45 * @throws NoSuchElementException 46 * when this {@code SortedSet} is empty. 47 */ first()48 public E first(); 49 50 /** 51 * Returns a {@code SortedSet} of the specified portion of this 52 * {@code SortedSet} which contains elements less than the end element. The 53 * returned {@code SortedSet} is backed by this {@code SortedSet} so changes 54 * to one set are reflected by the other. 55 * 56 * @param end 57 * the end element. 58 * @return a subset where the elements are less than {@code end}. 59 * @throws ClassCastException 60 * when the class of the end element is inappropriate for this 61 * SubSet. 62 * @throws NullPointerException 63 * when the end element is null and this {@code SortedSet} does 64 * not support null elements. 65 */ headSet(E end)66 public SortedSet<E> headSet(E end); 67 68 /** 69 * Returns the last element in this {@code SortedSet}. The last element is 70 * the highest element. 71 * 72 * @return the last element. 73 * @throws NoSuchElementException 74 * when this {@code SortedSet} is empty. 75 */ last()76 public E last(); 77 78 /** 79 * Returns a {@code SortedSet} of the specified portion of this 80 * {@code SortedSet} which contains elements greater or equal to the start 81 * element but less than the end element. The returned {@code SortedSet} is 82 * backed by this SortedMap so changes to one set are reflected by the 83 * other. 84 * 85 * @param start 86 * the start element. 87 * @param end 88 * the end element. 89 * @return a subset where the elements are greater or equal to {@code start} 90 * and less than {@code end}. 91 * @throws ClassCastException 92 * when the class of the start or end element is inappropriate 93 * for this SubSet. 94 * @throws NullPointerException 95 * when the start or end element is null and this 96 * {@code SortedSet} does not support null elements. 97 * @throws IllegalArgumentException 98 * when the start element is greater than the end element. 99 */ subSet(E start, E end)100 public SortedSet<E> subSet(E start, E end); 101 102 /** 103 * Returns a {@code SortedSet} of the specified portion of this 104 * {@code SortedSet} which contains elements greater or equal to the start 105 * element. The returned {@code SortedSet} is backed by this 106 * {@code SortedSet} so changes to one set are reflected by the other. 107 * 108 * @param start 109 * the start element. 110 * @return a subset where the elements are greater or equal to {@code start} . 111 * @throws ClassCastException 112 * when the class of the start element is inappropriate for this 113 * SubSet. 114 * @throws NullPointerException 115 * when the start element is null and this {@code SortedSet} 116 * does not support null elements. 117 */ tailSet(E start)118 public SortedSet<E> tailSet(E start); 119 } 120