Source for java.util.SortedSet

   1: /* SortedSet.java -- A set that makes guarantees about the order of its
   2:    elements
   3:    Copyright (C) 1998, 2001, 2004, 2005 Free Software Foundation, Inc.
   4: 
   5: This file is part of GNU Classpath.
   6: 
   7: GNU Classpath is free software; you can redistribute it and/or modify
   8: it under the terms of the GNU General Public License as published by
   9: the Free Software Foundation; either version 2, or (at your option)
  10: any later version.
  11: 
  12: GNU Classpath is distributed in the hope that it will be useful, but
  13: WITHOUT ANY WARRANTY; without even the implied warranty of
  14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15: General Public License for more details.
  16: 
  17: You should have received a copy of the GNU General Public License
  18: along with GNU Classpath; see the file COPYING.  If not, write to the
  19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 USA.
  21: 
  22: Linking this library statically or dynamically with other modules is
  23: making a combined work based on this library.  Thus, the terms and
  24: conditions of the GNU General Public License cover the whole
  25: combination.
  26: 
  27: As a special exception, the copyright holders of this library give you
  28: permission to link this library with independent modules to produce an
  29: executable, regardless of the license terms of these independent
  30: modules, and to copy and distribute the resulting executable under
  31: terms of your choice, provided that you also meet, for each linked
  32: independent module, the terms and conditions of the license of that
  33: module.  An independent module is a module which is not derived from
  34: or based on this library.  If you modify this library, you may extend
  35: this exception to your version of the library, but you are not
  36: obligated to do so.  If you do not wish to do so, delete this
  37: exception statement from your version. */
  38: 
  39: 
  40: package java.util;
  41: 
  42: /**
  43:  * A set which guarantees its iteration order. The elements in the set
  44:  * are related by the <i>natural ordering</i> if they are Comparable, or
  45:  * by the provided Comparator.  Additional operations take advantage of
  46:  * the sorted nature of the set.
  47:  * <p>
  48:  *
  49:  * All elements entered in the set must be mutually comparable; in other words,
  50:  * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
  51:  * must not throw a ClassCastException. The ordering must be <i>consistent
  52:  * with equals</i> (see {@link Comparator} for this definition), if the
  53:  * set is to obey the general contract of the Set interface.  If not,
  54:  * the results are well-defined, but probably not what you wanted.
  55:  * <p>
  56:  *
  57:  * It is recommended that all implementing classes provide four constructors:
  58:  * 1) one that takes no arguments and builds an empty set sorted by natural
  59:  * order of the elements; 2) one that takes a Comparator for the sorting order;
  60:  * 3) one that takes a Set and sorts according to the natural order of its
  61:  * elements; and 4) one that takes a SortedSet and sorts by the same
  62:  * comparator. Unfortunately, the Java language does not provide a way to
  63:  * enforce this.
  64:  *
  65:  * @author Original author unknown
  66:  * @author Eric Blake (ebb9@email.byu.edu)
  67:  * @see Set
  68:  * @see TreeSet
  69:  * @see SortedMap
  70:  * @see Collection
  71:  * @see Comparable
  72:  * @see Comparator
  73:  * @see ClassCastException
  74:  * @since 1.2
  75:  * @status updated to 1.4
  76:  */
  77: public interface SortedSet<E> extends Set<E>
  78: {
  79:   /**
  80:    * Returns the comparator used in sorting this set, or null if it is
  81:    * the elements' natural ordering.
  82:    *
  83:    * @return the sorting comparator
  84:    */
  85:   Comparator<? super E> comparator();
  86: 
  87:   /**
  88:    * Returns the first (lowest sorted) element in the set.
  89:    *
  90:    * @return the first element
  91:    * @throws NoSuchElementException if the set is empty.
  92:    */
  93:   E first();
  94: 
  95:   /**
  96:    * Returns a view of the portion of the set strictly less than toElement. The
  97:    * view is backed by this set, so changes in one show up in the other.
  98:    * The subset supports all optional operations of the original.
  99:    * <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: }