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 18package 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 * @since Android 1.0 31 */ 32public interface SortedSet<E> extends Set<E> { 33 34 /** 35 * Returns the comparator used to compare elements in this {@code SortedSet}. 36 * 37 * @return a comparator or null if the natural ordering is used. 38 * @since Android 1.0 39 */ 40 public Comparator<? super E> comparator(); 41 42 /** 43 * Returns the first element in this {@code SortedSet}. The first element 44 * is the lowest element. 45 * 46 * @return the first element. 47 * @throws NoSuchElementException 48 * when this {@code SortedSet} is empty. 49 * @since Android 1.0 50 */ 51 public E first(); 52 53 /** 54 * Returns a {@code SortedSet} of the specified portion of this 55 * {@code SortedSet} which contains elements less than the end element. The 56 * returned {@code SortedSet} is backed by this {@code SortedSet} so changes 57 * to one set are reflected by the other. 58 * 59 * @param end 60 * the end element. 61 * @return a subset where the elements are less than {@code end}. 62 * @throws ClassCastException 63 * when the class of the end element is inappropriate for this 64 * SubSet. 65 * @throws NullPointerException 66 * when the end element is null and this {@code SortedSet} does 67 * not support null elements. 68 * @since Android 1.0 69 */ 70 public SortedSet<E> headSet(E end); 71 72 /** 73 * Returns the last element in this {@code SortedSet}. The last element is 74 * the highest element. 75 * 76 * @return the last element. 77 * @throws NoSuchElementException 78 * when this {@code SortedSet} is empty. 79 * @since Android 1.0 80 */ 81 public E last(); 82 83 /** 84 * Returns a {@code SortedSet} of the specified portion of this 85 * {@code SortedSet} which contains elements greater or equal to the start 86 * element but less than the end element. The returned {@code SortedSet} is 87 * backed by this SortedMap so changes to one set are reflected by the 88 * other. 89 * 90 * @param start 91 * the start element. 92 * @param end 93 * the end element. 94 * @return a subset where the elements are greater or equal to {@code start} 95 * and less than {@code end}. 96 * @throws ClassCastException 97 * when the class of the start or end element is inappropriate 98 * for this SubSet. 99 * @throws NullPointerException 100 * when the start or end element is null and this 101 * {@code SortedSet} does not support null elements. 102 * @throws IllegalArgumentException 103 * when the start element is greater than the end element. 104 * @since Android 1.0 105 */ 106 public SortedSet<E> subSet(E start, E end); 107 108 /** 109 * Returns a {@code SortedSet} of the specified portion of this 110 * {@code SortedSet} which contains elements greater or equal to the start 111 * element. The returned {@code SortedSet} is backed by this 112 * {@code SortedSet} so changes to one set are reflected by the other. 113 * 114 * @param start 115 * the start element. 116 * @return a subset where the elements are greater or equal to {@code start} . 117 * @throws ClassCastException 118 * when the class of the start element is inappropriate for this 119 * SubSet. 120 * @throws NullPointerException 121 * when the start element is null and this {@code SortedSet} 122 * does not support null elements. 123 * @since Android 1.0 124 */ 125 public SortedSet<E> tailSet(E start); 126} 127