1 package org.djutils.immutablecollections;
2
3 import java.util.Comparator;
4 import java.util.NoSuchElementException;
5 import java.util.SortedMap;
6 import java.util.TreeMap;
7
8 /**
9 * A SortedMap interface without the methods that can change it. The return values of subMap, tailMap and headMap are all
10 * ImmutableSortedMaps.
11 * <p>
12 * Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
13 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
14 * distributed under a three-clause BSD-style license, which can be found at
15 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
16 * </p>
17 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
18 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
19 * @param <K> the key type of content of this Map
20 * @param <V> the value type of content of this Map
21 */
22 public interface ImmutableSortedMap<K, V> extends ImmutableMap<K, V>
23 {
24 /**
25 * Returns a modifiable copy of this immutable map.
26 * @return a modifiable copy of this immutable map.
27 */
28 @Override
29 SortedMap<K, V> toMap();
30
31 /**
32 * Returns the comparator used to order the keys in this immutable map, or <code>null</code> if this immutable map uses the
33 * {@linkplain Comparable natural ordering} of its keys.
34 * @return the comparator used to order the keys in this immutable map, or <code>null</code> if this immutable map uses the
35 * natural ordering of its keys
36 */
37 Comparator<? super K> comparator();
38
39 /**
40 * Returns a view of the portion of this immutable map whose keys range from <code>fromKey</code>, inclusive, to
41 * <code>toKey</code>, exclusive. (If <code>fromKey</code> and <code>toKey</code> are equal, the returned immutable map is
42 * empty.)
43 * <p>
44 * The result of this method is a new, immutable sorted map.
45 * @param fromKey K; low endpoint (inclusive) of the returned immutable map
46 * @param toKey K; high endpoint (exclusive) of the returned immutable map
47 * @return a new, immutable sorted map of the portion of this immutable map whose keys range from <code>fromKey</code>,
48 * inclusive, to <code>toKey</code>, exclusive
49 * @throws ClassCastException if <code>fromKey</code> and <code>toKey</code> cannot be compared to one another using this
50 * immutable map's comparator (or, if the immutable map has no comparator, using natural ordering).
51 * Implementations may, but are not required to, throw this exception if <code>fromKey</code> or
52 * <code>toKey</code> cannot be compared to keys currently in the immutable map.
53 * @throws NullPointerException if <code>fromKey</code> or <code>toKey</code> is null and this immutable map does not permit
54 * null keys
55 * @throws IllegalArgumentException if <code>fromKey</code> is greater than <code>toKey</code>; or if this immutable map
56 * itself has a restricted range, and <code>fromKey</code> or <code>toKey</code> lies outside the bounds of the
57 * range
58 */
59 ImmutableSortedMap<K, V> subMap(K fromKey, K toKey);
60
61 /**
62 * Returns a view of the portion of this immutable map whose keys are strictly less than <code>toKey</code>. The returned
63 * immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this immutable
64 * map, and vice-versa. The returned immutable map supports all optional immutable map operations that this immutable map
65 * supports.
66 * <p>
67 * The result of this method is a new, immutable sorted map.
68 * @param toKey K; high endpoint (exclusive) of the returned immutable map
69 * @return a view of the portion of this immutable map whose keys are strictly less than <code>toKey</code>
70 * @throws ClassCastException if <code>toKey</code> is not compatible with this immutable map's comparator (or, if the
71 * immutable map has no comparator, if <code>toKey</code> does not implement {@link Comparable}).
72 * Implementations may, but are not required to, throw this exception if <code>toKey</code> cannot be compared
73 * to keys currently in the immutable map.
74 * @throws NullPointerException if <code>toKey</code> is null and this immutable map does not permit null keys
75 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <code>toKey</code> lies outside
76 * the bounds of the range
77 */
78 ImmutableSortedMap<K, V> headMap(K toKey);
79
80 /**
81 * Returns a view of the portion of this immutable map whose keys are greater than or equal to <code>fromKey</code>. The
82 * returned immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this
83 * immutable map, and vice-versa. The returned immutable map supports all optional immutable map operations that this
84 * immutable map supports.
85 * <p>
86 * The result of this method is a new, immutable sorted map.
87 * @param fromKey K; low endpoint (inclusive) of the returned immutable map
88 * @return a view of the portion of this immutable map whose keys are greater than or equal to <code>fromKey</code>
89 * @throws ClassCastException if <code>fromKey</code> is not compatible with this immutable map's comparator (or, if the
90 * immutable map has no comparator, if <code>fromKey</code> does not implement {@link Comparable}).
91 * Implementations may, but are not required to, throw this exception if <code>fromKey</code> cannot be compared
92 * to keys currently in the immutable map.
93 * @throws NullPointerException if <code>fromKey</code> is null and this immutable map does not permit null keys
94 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <code>fromKey</code> lies
95 * outside the bounds of the range
96 */
97 ImmutableSortedMap<K, V> tailMap(K fromKey);
98
99 /**
100 * Returns the first (lowest) key currently in this immutable map.
101 * @return the first (lowest) key currently in this immutable map
102 * @throws NoSuchElementException if this immutable map is empty
103 */
104 K firstKey();
105
106 /**
107 * Returns the last (highest) key currently in this immutable map.
108 * @return the last (highest) key currently in this immutable map
109 * @throws NoSuchElementException if this immutable map is empty
110 */
111 K lastKey();
112
113 /**
114 * Return an ImmutableSortedSet view of the keys contained in this immutable map.
115 * @return an ImmutableSortedSet view of the keys contained in this immutable map
116 */
117 @Override
118 ImmutableSortedSet<K> keySet();
119
120 /**
121 * Force to redefine equals for the implementations of immutable collection classes.
122 * @param obj Object; the object to compare this collection with
123 * @return whether the objects are equal
124 */
125 @Override
126 boolean equals(Object obj);
127
128 /**
129 * Force to redefine hashCode for the implementations of immutable collection classes.
130 * @return the calculated hashCode
131 */
132 @Override
133 int hashCode();
134
135 /**
136 * Return an empty ImmutableSortedMap, backed by a TreeMap.
137 * @param <K> the key type
138 * @param <V> the value type
139 * @return ImmutableSortedMap<K, V>; an empty ImmutableSortedMap
140 */
141 static <K, V> ImmutableSortedMap<K, V> of()
142 {
143 return new ImmutableTreeMap<>(new TreeMap<K, V>(), Immutable.WRAP);
144 }
145
146 /**
147 * Return an ImmutableSortedMap with 1 entry, backed by a TreeMap.
148 * @param <K> the key type
149 * @param <V> the value type
150 * @param k1 K; key 1
151 * @param v1 V; value 1
152 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 1 entry, backed by a TreeMap
153 */
154 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1)
155 {
156 TreeMap<K, V> map = new TreeMap<>();
157 map.put(k1, v1);
158 return new ImmutableTreeMap<>(map, Immutable.WRAP);
159 }
160
161 /**
162 * Return an ImmutableSortedMap with 2 entries, backed by a TreeMap.
163 * @param <K> the key type
164 * @param <V> the value type
165 * @param k1 K; key 1
166 * @param v1 V; value 1
167 * @param k2 K; key 2
168 * @param v2 V; value 2
169 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 2 entries, backed by a TreeMap
170 */
171 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2)
172 {
173 TreeMap<K, V> map = new TreeMap<>();
174 map.put(k1, v1);
175 map.put(k2, v2);
176 return new ImmutableTreeMap<>(map, Immutable.WRAP);
177 }
178
179 /**
180 * Return an ImmutableSortedMap with 3 entries, backed by a TreeMap.
181 * @param <K> the key type
182 * @param <V> the value type
183 * @param k1 K; key 1
184 * @param v1 V; value 1
185 * @param k2 K; key 2
186 * @param v2 V; value 2
187 * @param k3 K; key 3
188 * @param v3 V; value 3
189 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 3 entries, backed by a TreeMap
190 */
191 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3)
192 {
193 TreeMap<K, V> map = new TreeMap<>();
194 map.put(k1, v1);
195 map.put(k2, v2);
196 map.put(k3, v3);
197 return new ImmutableTreeMap<>(map, Immutable.WRAP);
198 }
199
200 /**
201 * Return an ImmutableSortedMap with 4 entries, backed by a TreeMap.
202 * @param <K> the key type
203 * @param <V> the value type
204 * @param k1 K; key 1
205 * @param v1 V; value 1
206 * @param k2 K; key 2
207 * @param v2 V; value 2
208 * @param k3 K; key 3
209 * @param v3 V; value 3
210 * @param k4 K; key 4
211 * @param v4 V; value 4
212 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 4 entries, backed by a TreeMap
213 */
214 @SuppressWarnings("checkstyle:parameternumber")
215 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3,
216 final K k4, final V v4)
217 {
218 TreeMap<K, V> map = new TreeMap<>();
219 map.put(k1, v1);
220 map.put(k2, v2);
221 map.put(k3, v3);
222 map.put(k4, v4);
223 return new ImmutableTreeMap<>(map, Immutable.WRAP);
224 }
225
226 /**
227 * Return an ImmutableSortedMap with 5 entries, backed by a TreeMap.
228 * @param <K> the key type
229 * @param <V> the value type
230 * @param k1 K; key 1
231 * @param v1 V; value 1
232 * @param k2 K; key 2
233 * @param v2 V; value 2
234 * @param k3 K; key 3
235 * @param v3 V; value 3
236 * @param k4 K; key 4
237 * @param v4 V; value 4
238 * @param k5 K; key 5
239 * @param v5 V; value 5
240 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 5 entries, backed by a TreeMap
241 */
242 @SuppressWarnings("checkstyle:parameternumber")
243 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3,
244 final K k4, final V v4, final K k5, final V v5)
245 {
246 TreeMap<K, V> map = new TreeMap<>();
247 map.put(k1, v1);
248 map.put(k2, v2);
249 map.put(k3, v3);
250 map.put(k4, v4);
251 map.put(k5, v5);
252 return new ImmutableTreeMap<>(map, Immutable.WRAP);
253 }
254
255 /**
256 * Return an ImmutableSortedMap with 6 entries, backed by a TreeMap.
257 * @param <K> the key type
258 * @param <V> the value type
259 * @param k1 K; key 1
260 * @param v1 V; value 1
261 * @param k2 K; key 2
262 * @param v2 V; value 2
263 * @param k3 K; key 3
264 * @param v3 V; value 3
265 * @param k4 K; key 4
266 * @param v4 V; value 4
267 * @param k5 K; key 5
268 * @param v5 V; value 5
269 * @param k6 K; key 6
270 * @param v6 V; value 6
271 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 6 entries, backed by a TreeMap
272 */
273 @SuppressWarnings("checkstyle:parameternumber")
274 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3,
275 final K k4, final V v4, final K k5, final V v5, final K k6, final V v6)
276 {
277 TreeMap<K, V> map = new TreeMap<>();
278 map.put(k1, v1);
279 map.put(k2, v2);
280 map.put(k3, v3);
281 map.put(k4, v4);
282 map.put(k5, v5);
283 map.put(k6, v6);
284 return new ImmutableTreeMap<>(map, Immutable.WRAP);
285 }
286
287 /**
288 * Return an ImmutableSortedMap with 7 entries, backed by a TreeMap.
289 * @param <K> the key type
290 * @param <V> the value type
291 * @param k1 K; key 1
292 * @param v1 V; value 1
293 * @param k2 K; key 2
294 * @param v2 V; value 2
295 * @param k3 K; key 3
296 * @param v3 V; value 3
297 * @param k4 K; key 4
298 * @param v4 V; value 4
299 * @param k5 K; key 5
300 * @param v5 V; value 5
301 * @param k6 K; key 6
302 * @param v6 V; value 6
303 * @param k7 K; key 7
304 * @param v7 V; value 7
305 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 7 entries, backed by a TreeMap
306 */
307 @SuppressWarnings("checkstyle:parameternumber")
308 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3,
309 final K k4, final V v4, final K k5, final V v5, final K k6, final V v6, final K k7, final V v7)
310 {
311 TreeMap<K, V> map = new TreeMap<>();
312 map.put(k1, v1);
313 map.put(k2, v2);
314 map.put(k3, v3);
315 map.put(k4, v4);
316 map.put(k5, v5);
317 map.put(k6, v6);
318 map.put(k7, v7);
319 return new ImmutableTreeMap<>(map, Immutable.WRAP);
320 }
321
322 /**
323 * Return an ImmutableSortedMap with 8 entries, backed by a TreeMap.
324 * @param <K> the key type
325 * @param <V> the value type
326 * @param k1 K; key 1
327 * @param v1 V; value 1
328 * @param k2 K; key 2
329 * @param v2 V; value 2
330 * @param k3 K; key 3
331 * @param v3 V; value 3
332 * @param k4 K; key 4
333 * @param v4 V; value 4
334 * @param k5 K; key 5
335 * @param v5 V; value 5
336 * @param k6 K; key 6
337 * @param v6 V; value 6
338 * @param k7 K; key 7
339 * @param v7 V; value 7
340 * @param k8 K; key 8
341 * @param v8 V; value 8
342 * @return ImmutableSortedMap<K, V>; an ImmutableSortedMap with 8 entries, backed by a TreeMap
343 */
344 @SuppressWarnings("checkstyle:parameternumber")
345 static <K, V> ImmutableSortedMap<K, V> of(final K k1, final V v1, final K k2, final V v2, final K k3, final V v3,
346 final K k4, final V v4, final K k5, final V v5, final K k6, final V v6, final K k7, final V v7, final K k8,
347 final V v8)
348 {
349 TreeMap<K, V> map = new TreeMap<>();
350 map.put(k1, v1);
351 map.put(k2, v2);
352 map.put(k3, v3);
353 map.put(k4, v4);
354 map.put(k5, v5);
355 map.put(k6, v6);
356 map.put(k7, v7);
357 map.put(k8, v8);
358 return new ImmutableTreeMap<>(map, Immutable.WRAP);
359 }
360
361 }