001/* SortedSet.java -- A set that makes guarantees about the order of its 002 elements 003 Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc. 004 005This file is part of GNU Classpath. 006 007GNU Classpath is free software; you can redistribute it and/or modify 008it under the terms of the GNU General Public License as published by 009the Free Software Foundation; either version 2, or (at your option) 010any later version. 011 012GNU Classpath is distributed in the hope that it will be useful, but 013WITHOUT ANY WARRANTY; without even the implied warranty of 014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015General Public License for more details. 016 017You should have received a copy of the GNU General Public License 018along with GNU Classpath; see the file COPYING. If not, write to the 019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02002110-1301 USA. 021 022Linking this library statically or dynamically with other modules is 023making a combined work based on this library. Thus, the terms and 024conditions of the GNU General Public License cover the whole 025combination. 026 027As a special exception, the copyright holders of this library give you 028permission to link this library with independent modules to produce an 029executable, regardless of the license terms of these independent 030modules, and to copy and distribute the resulting executable under 031terms of your choice, provided that you also meet, for each linked 032independent module, the terms and conditions of the license of that 033module. An independent module is a module which is not derived from 034or based on this library. If you modify this library, you may extend 035this exception to your version of the library, but you are not 036obligated to do so. If you do not wish to do so, delete this 037exception statement from your version. */ 038 039 040package java.util; 041 042/** 043 * A set which guarantees its iteration order. The elements in the set 044 * are related by the <i>natural ordering</i> if they are Comparable, or 045 * by the provided Comparator. Additional operations take advantage of 046 * the sorted nature of the set. 047 * <p> 048 * 049 * All elements entered in the set must be mutually comparable; in other words, 050 * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code> 051 * must not throw a ClassCastException. The ordering must be <i>consistent 052 * with equals</i> (see {@link Comparator} for this definition), if the 053 * set is to obey the general contract of the Set interface. If not, 054 * the results are well-defined, but probably not what you wanted. 055 * <p> 056 * 057 * It is recommended that all implementing classes provide four constructors: 058 * 1) one that takes no arguments and builds an empty set sorted by natural 059 * order of the elements; 2) one that takes a Comparator for the sorting order; 060 * 3) one that takes a Set and sorts according to the natural order of its 061 * elements; and 4) one that takes a SortedSet and sorts by the same 062 * comparator. Unfortunately, the Java language does not provide a way to 063 * enforce this. 064 * 065 * @author Original author unknown 066 * @author Eric Blake (ebb9@email.byu.edu) 067 * @see Set 068 * @see TreeSet 069 * @see SortedMap 070 * @see Collection 071 * @see Comparable 072 * @see Comparator 073 * @see ClassCastException 074 * @since 1.2 075 * @status updated to 1.4 076 */ 077public interface SortedSet<E> extends Set<E> 078{ 079 /** 080 * Returns the comparator used in sorting this set, or null if it is 081 * the elements' natural ordering. 082 * 083 * @return the sorting comparator 084 */ 085 Comparator<? super E> comparator(); 086 087 /** 088 * Returns the first (lowest sorted) element in the set. 089 * 090 * @return the first element 091 * @throws NoSuchElementException if the set is empty. 092 */ 093 E first(); 094 095 /** 096 * Returns a view of the portion of the set strictly less than toElement. The 097 * view is backed by this set, so changes in one show up in the other. 098 * The subset supports all optional operations of the original. 099 * <p> 100 * 101 * The returned set throws an IllegalArgumentException any time an element is 102 * used which is out of the range of toElement. Note that the endpoint, toElement, 103 * is not included; if you want this value included, pass its successor object in to 104 * toElement. For example, for Integers, you could request 105 * <code>headSet(new Integer(limit.intValue() + 1))</code>. 106 * 107 * @param toElement the exclusive upper range of the subset 108 * @return the subset 109 * @throws ClassCastException if toElement is not comparable to the set 110 * contents 111 * @throws IllegalArgumentException if this is a subSet, and toElement is out 112 * of range 113 * @throws NullPointerException if toElement is null but the set does not 114 * allow null elements 115 */ 116 SortedSet<E> headSet(E toElement); 117 118 /** 119 * Returns the last (highest sorted) element in the set. 120 * 121 * @return the last element 122 * @throws NoSuchElementException if the set is empty. 123 */ 124 E last(); 125 126 /** 127 * Returns a view of the portion of the set greater than or equal to 128 * fromElement, and strictly less than toElement. The view is backed by 129 * this set, so changes in one show up in the other. The subset supports all 130 * optional operations of the original. 131 * <p> 132 * 133 * The returned set throws an IllegalArgumentException any time an element is 134 * used which is out of the range of fromElement and toElement. Note that the 135 * lower endpoint is included, but the upper is not; if you want to 136 * change the inclusion or exclusion of an endpoint, pass its successor 137 * object in instead. For example, for Integers, you can request 138 * <code>subSet(new Integer(lowlimit.intValue() + 1), 139 * new Integer(highlimit.intValue() + 1))</code> to reverse 140 * the inclusiveness of both endpoints. 141 * 142 * @param fromElement the inclusive lower range of the subset 143 * @param toElement the exclusive upper range of the subset 144 * @return the subset 145 * @throws ClassCastException if fromElement or toElement is not comparable 146 * to the set contents 147 * @throws IllegalArgumentException if this is a subSet, and fromElement or 148 * toElement is out of range 149 * @throws NullPointerException if fromElement or toElement is null but the 150 * set does not allow null elements 151 */ 152 SortedSet<E> subSet(E fromElement, E toElement); 153 154 /** 155 * Returns a view of the portion of the set greater than or equal to 156 * fromElement. The view is backed by this set, so changes in one show up 157 * in the other. The subset supports all optional operations of the original. 158 * <p> 159 * 160 * The returned set throws an IllegalArgumentException any time an element is 161 * used which is out of the range of fromElement. Note that the endpoint, 162 * fromElement, is included; if you do not want this value to be included, pass its 163 * successor object in to fromElement. For example, for Integers, you could request 164 * <code>tailSet(new Integer(limit.intValue() + 1))</code>. 165 * 166 * @param fromElement the inclusive lower range of the subset 167 * @return the subset 168 * @throws ClassCastException if fromElement is not comparable to the set 169 * contents 170 * @throws IllegalArgumentException if this is a subSet, and fromElement is 171 * out of range 172 * @throws NullPointerException if fromElement is null but the set does not 173 * allow null elements 174 */ 175 SortedSet<E> tailSet(E fromElement); 176}