libjava/java/util/SortedSet.java

   1 /* SortedSet.java -- A set that makes guarantees about the order of its
   2    elements
   3    Copyright (C) 1998, 2001, 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., 59 Temple Place, Suite 330, Boston, MA
  20 02111-1307 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 extends Set
  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 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   Object 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 headSet(Object 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   Object 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 subSet(Object fromElement, Object 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 tailSet(Object fromElement);
 176 }