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