1 package org.djutils.immutablecollections;
2
3 import java.util.Comparator;
4 import java.util.NoSuchElementException;
5 import java.util.SortedMap;
6
7 /**
8 * A SortedMap interface without the methods that can change it. The return values of subMap, tailMap and headMap are all
9 * ImmutableSortedMaps.
10 * <p>
11 * Copyright (c) 2016-2019 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
12 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
13 * distributed under a three-clause BSD-style license, which can be found at
14 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
15 * </p>
16 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
18 * @author <a href="https://www.transport.citg.tudelft.nl">Wouter Schakel</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 <code>toKey</code>,
41 * exclusive. (If <code>fromKey</code> and <code>toKey</code> are equal, the returned immutable map is empty.)
42 * <p>
43 * The result of this method is a new, immutable sorted map.
44 * @param fromKey K; low endpoint (inclusive) of the returned immutable map
45 * @param toKey K; high endpoint (exclusive) of the returned immutable map
46 * @return a new, immutable sorted map of the portion of this immutable map whose keys range from <code>fromKey</code>,
47 * inclusive, to <code>toKey</code>, exclusive
48 * @throws ClassCastException if <code>fromKey</code> and <code>toKey</code> cannot be compared to one another using this immutable
49 * map's comparator (or, if the immutable map has no comparator, using natural ordering). Implementations may,
50 * but are not required to, throw this exception if <code>fromKey</code> or <code>toKey</code> cannot be compared to
51 * keys currently in the immutable map.
52 * @throws NullPointerException if <code>fromKey</code> or <code>toKey</code> is null and this immutable map does not permit null
53 * keys
54 * @throws IllegalArgumentException if <code>fromKey</code> is greater than <code>toKey</code>; or if this immutable map itself has
55 * a restricted range, and <code>fromKey</code> or <code>toKey</code> lies outside the bounds of the range
56 */
57 ImmutableSortedMap<K, V> subMap(K fromKey, K toKey);
58
59 /**
60 * Returns a view of the portion of this immutable map whose keys are strictly less than <code>toKey</code>. The returned
61 * immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this immutable
62 * map, and vice-versa. The returned immutable map supports all optional immutable map operations that this immutable map
63 * supports.
64 * <p>
65 * The result of this method is a new, immutable sorted map.
66 * @param toKey K; high endpoint (exclusive) of the returned immutable map
67 * @return a view of the portion of this immutable map whose keys are strictly less than <code>toKey</code>
68 * @throws ClassCastException if <code>toKey</code> is not compatible with this immutable map's comparator (or, if the immutable
69 * map has no comparator, if <code>toKey</code> does not implement {@link Comparable}). Implementations may, but are
70 * not required to, throw this exception if <code>toKey</code> cannot be compared to keys currently in the immutable
71 * map.
72 * @throws NullPointerException if <code>toKey</code> is null and this immutable map does not permit null keys
73 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <code>toKey</code> lies outside the
74 * bounds of the range
75 */
76 ImmutableSortedMap<K, V> headMap(K toKey);
77
78 /**
79 * Returns a view of the portion of this immutable map whose keys are greater than or equal to <code>fromKey</code>. The
80 * returned immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this
81 * immutable map, and vice-versa. The returned immutable map supports all optional immutable map operations that this
82 * immutable map supports.
83 * <p>
84 * The result of this method is a new, immutable sorted map.
85 * @param fromKey K; low endpoint (inclusive) of the returned immutable map
86 * @return a view of the portion of this immutable map whose keys are greater than or equal to <code>fromKey</code>
87 * @throws ClassCastException if <code>fromKey</code> is not compatible with this immutable map's comparator (or, if the
88 * immutable map has no comparator, if <code>fromKey</code> does not implement {@link Comparable}). Implementations
89 * may, but are not required to, throw this exception if <code>fromKey</code> cannot be compared to keys currently
90 * in the immutable map.
91 * @throws NullPointerException if <code>fromKey</code> is null and this immutable map does not permit null keys
92 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <code>fromKey</code> lies outside
93 * the bounds of the range
94 */
95 ImmutableSortedMap<K, V> tailMap(K fromKey);
96
97 /**
98 * Returns the first (lowest) key currently in this immutable map.
99 * @return the first (lowest) key currently in this immutable map
100 * @throws NoSuchElementException if this immutable map is empty
101 */
102 K firstKey();
103
104 /**
105 * Returns the last (highest) key currently in this immutable map.
106 * @return the last (highest) key currently in this immutable map
107 * @throws NoSuchElementException if this immutable map is empty
108 */
109 K lastKey();
110
111 /**
112 * Return an ImmutableSortedSet view of the keys contained in this immutable map.
113 * @return an ImmutableSortedSet view of the keys contained in this immutable map
114 */
115 @Override
116 ImmutableSortedSet<K> keySet();
117
118 /**
119 * Force to redefine equals for the implementations of immutable collection classes.
120 * @param obj Object; the object to compare this collection with
121 * @return whether the objects are equal
122 */
123 @Override
124 boolean equals(Object obj);
125
126 /**
127 * Force to redefine hashCode for the implementations of immutable collection classes.
128 * @return the calculated hashCode
129 */
130 @Override
131 int hashCode();
132
133 }