1 package org.djutils.immutablecollections;
2
3 import java.util.Collections;
4 import java.util.Comparator;
5 import java.util.NavigableMap;
6
7 /**
8 * A {@link ImmutableSortedMap} extended with navigation methods reporting closest matches for given search targets. Methods
9 * {@code lowerKey}, {@code floorKey}, {@code ceilingKey}, and {@code higherKey} return keys respectively less than, less than
10 * or equal, greater than or equal, and greater than a given key, returning {@code null} if there is no such key. All methods
11 * from java.util.NavigableMap that can change the map have been left out.
12 * <p>
13 * Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
14 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is
15 * distributed under a three-clause BSD-style license, which can be found at
16 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>.
17 * </p>
18 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
19 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
20 * @param <K> the key type of content of this Map
21 * @param <V> the value type of content of this Map
22 */
23 public interface ImmutableNavigableMap<K, V> extends ImmutableSortedMap<K, V>
24 {
25 /**
26 * Returns a modifiable copy of this immutable map.
27 * @return a modifiable copy of this immutable map.
28 */
29 @Override
30 NavigableMap<K, V> toMap();
31
32 /**
33 * Returns a {@link ImmutableSortedSet} view of the keys contained in this map.
34 * @return an immutable sorted set of the keys contained in this map
35 */
36 @Override
37 ImmutableSortedSet<K> keySet();
38
39 /**
40 * Returns the greatest key in this immutable map strictly less than the given key, or {@code null} if there is no such key.
41 * @param e K; the value to match
42 * @return the greatest key less than {@code e}, or {@code null} if there is no such key
43 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
44 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
45 */
46 K lowerKey(K e);
47
48 /**
49 * Returns the greatest key in this immutable map less than or equal to the given key, or {@code null} if there is no such
50 * key.
51 * @param e K; the value to match
52 * @return the greatest key less than or equal to {@code e}, or {@code null} if there is no such key
53 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
54 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
55 */
56 K floorKey(K e);
57
58 /**
59 * Returns the least key in this immutable map greater than or equal to the given key, or {@code null} if there is no such
60 * key.
61 * @param e K; the value to match
62 * @return the least key greater than or equal to {@code e}, or {@code null} if there is no such key
63 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
64 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
65 */
66 K ceilingKey(K e);
67
68 /**
69 * Returns the least key in this immutable map strictly greater than the given key, or {@code null} if there is no such key.
70 * @param e K; the value to match
71 * @return the least key greater than {@code e}, or {@code null} if there is no such key
72 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
73 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
74 */
75 K higherKey(K e);
76
77 /**
78 * Returns a reverse order view of the keys contained in this immutable map.
79 * <p>
80 * The returned immutable map has an ordering equivalent to
81 * <code>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</code>. The expression
82 * {@code s.descendingMap().descendingMap()} returns a view of {@code s} essentially equivalent to {@code s}.
83 * @return a reverse order view of this immutable map
84 */
85 ImmutableNavigableMap<K, V> descendingMap();
86
87 /**
88 * Returns a view of the portion of this immutable map whose keys range from {@code fromKey} to {@code toKey}. If
89 * {@code fromKey} and {@code toKey} are equal, the returned immutable map is empty unless {@code fromInclusive} and
90 * {@code toInclusive} are both true.
91 * @param fromKey K; low endpoint of the returned immutable map
92 * @param fromInclusive boolean; {@code true} if the low endpoint is to be included in the returned view
93 * @param toKey K; high endpoint of the returned immutable map
94 * @param toInclusive boolean; {@code true} if the high endpoint is to be included in the returned view
95 * @return a view of the portion of this immutable map whose keys range from {@code fromKey}, inclusive, to {@code toKey},
96 * exclusive
97 * @throws ClassCastException if {@code fromKey} and {@code toKey} cannot be compared to one another using this immutable
98 * map's comparator (or, if the immutable map has no comparator, using natural ordering). Implementations may,
99 * but are not required to, throw this exception if {@code fromKey} or {@code toKey} cannot be compared to keys
100 * currently in the immutable map.
101 * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this immutable map does not permit null keys
102 * @throws IllegalArgumentException if {@code fromKey} is greater than {@code toKey}; or if this immutable map itself has a
103 * restricted range, and {@code fromKey} or {@code toKey} lies outside the bounds of the range.
104 */
105 ImmutableNavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
106
107 /**
108 * Returns a view of the portion of this immutable map whose keys are less than (or equal to, if {@code inclusive} is true)
109 * {@code toKey}.
110 * @param toKey K; high endpoint of the returned immutable map
111 * @param inclusive boolean; {@code true} if the high endpoint is to be included in the returned view
112 * @return a view of the portion of this immutable map whose keys are less than (or equal to, if {@code inclusive} is true)
113 * {@code toKey}
114 * @throws ClassCastException if {@code toKey} is not compatible with this immutable map's comparator (or, if the immutable
115 * map has no comparator, if {@code toKey} does not implement {@link Comparable}). Implementations may, but are
116 * not required to, throw this exception if {@code toKey} cannot be compared to keys currently in the immutable
117 * map.
118 * @throws NullPointerException if {@code toKey} is null and this immutable map does not permit null keys
119 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and {@code toKey} lies outside the
120 * bounds of the range
121 */
122 ImmutableNavigableMap<K, V> headMap(K toKey, boolean inclusive);
123
124 /**
125 * Returns a view of the portion of this immutable map whose keys are greater than (or equal to, if {@code inclusive} is
126 * true) {@code fromKey}.
127 * @param fromKey K; low endpoint of the returned immutable map
128 * @param inclusive boolean; {@code true} if the low endpoint is to be included in the returned view
129 * @return a view of the portion of this immutable map whose keys are greater than or equal to {@code fromKey}
130 * @throws ClassCastException if {@code fromKey} is not compatible with this immutable map's comparator (or, if the
131 * immutable map has no comparator, if {@code fromKey} does not implement {@link Comparable}). Implementations
132 * may, but are not required to, throw this exception if {@code fromKey} cannot be compared to keys currently in
133 * the immutable map.
134 * @throws NullPointerException if {@code fromKey} is null and this immutable map does not permit null keys
135 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and {@code fromKey} lies outside
136 * the bounds of the range
137 */
138 ImmutableNavigableMap<K, V> tailMap(K fromKey, boolean inclusive);
139
140 /**
141 * Force to redefine equals for the implementations of immutable collection classes.
142 * @param obj Object; the object to compare this collection with
143 * @return whether the objects are equal
144 */
145 @Override
146 boolean equals(Object obj);
147
148 /**
149 * Force to redefine hashCode for the implementations of immutable collection classes.
150 * @return the calculated hashCode
151 */
152 @Override
153 int hashCode();
154
155 }