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 |
|
|
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 |
} |
} |