/[classpath]/classpath/java/util/SortedSet.java
ViewVC logotype

Diff of /classpath/java/util/SortedSet.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.4 by bryce, Thu Oct 26 10:19:01 2000 UTC revision 1.5 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* SortedSet.java -- A set that makes guarantees about the order of its  /* SortedSet.java -- A set that makes guarantees about the order of its
2     elements     elements
3     Copyright (C) 1998 Free Software Foundation, Inc.     Copyright (C) 1998, 2001 Free Software Foundation, Inc.
4    
5  This file is part of GNU Classpath.  This file is part of GNU Classpath.
6    
# Line 26  This exception does not however invalida Line 26  This exception does not however invalida
26  executable file might be covered by the GNU General Public License. */  executable file might be covered by the GNU General Public License. */
27    
28    
 // TO DO:  
 // ~ Doc comments for everything.  
   
29  package java.util;  package java.util;
30    
31    /**
32     * A set which guarantees its iteration order. The elements in the set
33     * are related by the <i>natural ordering</i> if they are Comparable, or
34     * by the provided Comparator.  Additional operations take advantage of
35     * the sorted nature of the set.
36     * <p>
37     *
38     * All elements entered in the set must be mutually comparable; in other words,
39     * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
40     * must not throw a ClassCastException. The ordering must be <i>consistent
41     * with equals</i> (see {@link Comparator} for this definition), if the
42     * map is to obey the general contract of the Set interface.  If not,
43     * the results are well-defined, but probably not what you wanted.
44     * <p>
45     *
46     * It is recommended that all implementing classes provide four constructors:
47     * 1) one that takes no arguments and builds an empty set sorted by natural
48     * order of the elements; 2) one that takes a Comparator for the sorting order;
49     * 3) one that takes a Set and sorts according to the natural order of its
50     * elements; and 4) one that takes a SortedSet and sorts by the same
51     * comparator. Unfortunately, the Java language does not provide a way to
52     * enforce this.
53     *
54     * @author Original author unknown
55     * @author Eric Blake <ebb9@email.byu.edu>
56     * @see Set
57     * @see TreeSet
58     * @see SortedMap
59     * @see Collection
60     * @see Comparable
61     * @see Comparator
62     * @see ClassCastException
63     * @since 1.2
64     * @status updated to 1.4
65     */
66  public interface SortedSet extends Set  public interface SortedSet extends Set
67  {  {
68      /**
69       * Returns the comparator used in sorting this set, or null if it is
70       * the elements' natural ordering.
71       *
72       * @return the sorting comparator
73       */
74    Comparator comparator();    Comparator comparator();
75    
76      /**
77       * Returns the first (lowest sorted) element in the map.
78       *
79       * @return the first element
80       */
81    Object first();    Object first();
82    
83      /**
84       * Returns a view of the portion of the set strictly less than toElement. The
85       * view is backed by this set, so changes in one show up in the other.
86       * The subset supports all optional operations of the original.
87       * <p>
88       *
89       * The returned set throws an IllegalArgumentException any time an element is
90       * used which is out of the range of toElement. Note that the endpoint is not
91       * included; if you want the endpoint, pass the successor object in to
92       * toElement.  For example, for Strings, you can request
93       * <code>headSet(limit + "\0")</code>.
94       *
95       * @param toElement the exclusive upper range of the subset
96       * @return the subset
97       * @throws ClassCastException if toElement is not comparable to the set
98       *         contents
99       * @throws IllegalArgumentException if this is a subSet, and toElement is out
100       *         of range
101       * @throws NullPointerException if toElement is null but the map does not
102       *         allow null elements
103       */
104    SortedSet headSet(Object toElement);    SortedSet headSet(Object toElement);
105    
106      /**
107       * Returns the last (highest sorted) element in the map.
108       *
109       * @return the last element
110       */
111    Object last();    Object last();
112    
113      /**
114       * Returns a view of the portion of the set greater than or equal to
115       * fromElement, and strictly less than toElement. The view is backed by
116       * this set, so changes in one show up in the other. The subset supports all
117       * optional operations of the original.
118       * <p>
119       *
120       * The returned set throws an IllegalArgumentException any time an element is
121       * used which is out of the range of fromElement and toElement. Note that the
122       * lower endpoint is included, but the upper is not; if you want to
123       * change the inclusion or exclusion of an endpoint, pass the successor
124       * object in instead.  For example, for Strings, you can request
125       * <code>subSet(lowlimit + "\0", highlimit + "\0")</code> to reverse
126       * the inclusiveness of both endpoints.
127       *
128       * @param fromElement the inclusive lower range of the subset
129       * @param toElement the exclusive upper range of the subset
130       * @return the subset
131       * @throws ClassCastException if fromElement or toElement is not comparable
132       *         to the set contents
133       * @throws IllegalArgumentException if this is a subSet, and fromElement or
134       *         toElement is out of range
135       * @throws NullPointerException if fromElement or toElement is null but the
136       *         set does not allow null elements
137       */
138    SortedSet subSet(Object fromElement, Object toElement);    SortedSet subSet(Object fromElement, Object toElement);
139    
140      /**
141       * Returns a view of the portion of the set greater than or equal to
142       * fromElement. The view is backed by this set, so changes in one show up
143       * in the other. The subset supports all optional operations of the original.
144       * <p>
145       *
146       * The returned set throws an IllegalArgumentException any time an element is
147       * used which is out of the range of fromElement. Note that the endpoint is
148       * included; if you do not want the endpoint, pass the successor object in
149       * to fromElement.  For example, for Strings, you can request
150       * <code>tailSet(limit + "\0")</code>.
151       *
152       * @param fromElement the inclusive lower range of the subset
153       * @return the subset
154       * @throws ClassCastException if fromElement is not comparable to the set
155       *         contents
156       * @throws IllegalArgumentException if this is a subSet, and fromElement is
157       *         out of range
158       * @throws NullPointerException if fromElement is null but the set does not
159       *         allow null elements
160       */
161    SortedSet tailSet(Object fromElement);    SortedSet tailSet(Object fromElement);
162  }  }

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26