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    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    
040    package 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     */
077    public 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    }