1 package org.opentrafficsim.base.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) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
14 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
15 * </p>
16 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
17 * initial version May 7, 2016 <br>
18 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
19 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
20 * @author <a href="http://www.transport.citg.tudelft.nl">Wouter Schakel</a>
21 * @param <K> the key type of content of this Map
22 * @param <V> the value type of content of this Map
23 */
24 public interface ImmutableNavigableMap<K, V> extends ImmutableSortedMap<K, V>
25 {
26 /**
27 * Returns a modifiable copy of this immutable map.
28 * @return a modifiable copy of this immutable map.
29 */
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 ImmutableSortedSet<K> keySet();
37
38 /**
39 * Returns the greatest key in this immutable map strictly less than the given key, or {@code null} if there is no such key.
40 * @param e the value to match
41 * @return the greatest key less than {@code e}, or {@code null} if there is no such key
42 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
43 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
44 */
45 K lowerKey(K e);
46
47 /**
48 * Returns the greatest key in this immutable map less than or equal to the given key, or {@code null} if there is no such
49 * key.
50 * @param e the value to match
51 * @return the greatest key less than or equal to {@code e}, or {@code null} if there is no such key
52 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
53 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
54 */
55 K floorKey(K e);
56
57 /**
58 * Returns the least key in this immutable map greater than or equal to the given key, or {@code null} if there is no such
59 * key.
60 * @param e the value to match
61 * @return the least key greater than or equal to {@code e}, or {@code null} if there is no such key
62 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
63 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
64 */
65 K ceilingKey(K e);
66
67 /**
68 * Returns the least key in this immutable map strictly greater than the given key, or {@code null} if there is no such key.
69 * @param e the value to match
70 * @return the least key greater than {@code e}, or {@code null} if there is no such key
71 * @throws ClassCastException if the specified key cannot be compared with the keys currently in the immutable map
72 * @throws NullPointerException if the specified key is null and this immutable map does not permit null keys
73 */
74 K higherKey(K e);
75
76 /**
77 * Returns a reverse order view of the keys contained in this immutable map.
78 * <p>
79 * The returned immutable map has an ordering equivalent to
80 * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>. The expression
81 * {@code s.descendingMap().descendingMap()} returns a view of {@code s} essentially equivalent to {@code s}.
82 * @return a reverse order view of this immutable map
83 */
84 ImmutableNavigableMap<K, V> descendingMap();
85
86 /**
87 * Returns a view of the portion of this immutable map whose keys range from {@code fromKey} to {@code toKey}. If
88 * {@code fromKey} and {@code toKey} are equal, the returned immutable map is empty unless {@code fromInclusive} and
89 * {@code toInclusive} are both true.
90 * @param fromKey low endpoint of the returned immutable map
91 * @param fromInclusive {@code true} if the low endpoint is to be included in the returned view
92 * @param toKey high endpoint of the returned immutable map
93 * @param toInclusive {@code true} if the high endpoint is to be included in the returned view
94 * @return a view of the portion of this immutable map whose keys range from {@code fromKey}, inclusive, to {@code toKey},
95 * exclusive
96 * @throws ClassCastException if {@code fromKey} and {@code toKey} cannot be compared to one another using this immutable
97 * map's comparator (or, if the immutable map has no comparator, using natural ordering). Implementations may,
98 * but are not required to, throw this exception if {@code fromKey} or {@code toKey} cannot be compared to keys
99 * currently in the immutable map.
100 * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this immutable map does not permit null keys
101 * @throws IllegalArgumentException if {@code fromKey} is greater than {@code toKey}; or if this immutable map itself has a
102 * restricted range, and {@code fromKey} or {@code toKey} lies outside the bounds of the range.
103 */
104 ImmutableNavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
105
106 /**
107 * Returns a view of the portion of this immutable map whose keys are less than (or equal to, if {@code inclusive} is true)
108 * {@code toKey}.
109 * @param toKey high endpoint of the returned immutable map
110 * @param inclusive {@code true} if the high endpoint is to be included in the returned view
111 * @return a view of the portion of this immutable map whose keys are less than (or equal to, if {@code inclusive} is true)
112 * {@code toKey}
113 * @throws ClassCastException if {@code toKey} is not compatible with this immutable map's comparator (or, if the immutable
114 * map has no comparator, if {@code toKey} does not implement {@link Comparable}). Implementations may, but are
115 * not required to, throw this exception if {@code toKey} cannot be compared to keys currently in the immutable
116 * map.
117 * @throws NullPointerException if {@code toKey} is null and this immutable map does not permit null keys
118 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and {@code toKey} lies outside the
119 * bounds of the range
120 */
121 ImmutableNavigableMap<K, V> headMap(K toKey, boolean inclusive);
122
123 /**
124 * Returns a view of the portion of this immutable map whose keys are greater than (or equal to, if {@code inclusive} is
125 * true) {@code fromKey}.
126 * @param fromKey low endpoint of the returned immutable map
127 * @param inclusive {@code true} if the low endpoint is to be included in the returned view
128 * @return a view of the portion of this immutable map whose keys are greater than or equal to {@code fromKey}
129 * @throws ClassCastException if {@code fromKey} is not compatible with this immutable map's comparator (or, if the
130 * immutable map has no comparator, if {@code fromKey} does not implement {@link Comparable}). Implementations
131 * may, but are not required to, throw this exception if {@code fromKey} cannot be compared to keys currently in
132 * the immutable map.
133 * @throws NullPointerException if {@code fromKey} is null and this immutable map does not permit null keys
134 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and {@code fromKey} lies outside
135 * the bounds of the range
136 */
137 ImmutableNavigableMap<K, V> tailMap(K fromKey, boolean inclusive);
138
139 /**
140 * Force to redefine equals for the implementations of immutable collection classes.
141 * @param obj the object to compare this collection with
142 * @return whether the objects are equal
143 */
144 boolean equals(final Object obj);
145
146 /**
147 * Force to redefine hashCode for the implementations of immutable collection classes.
148 * @return the calculated hashCode
149 */
150 int hashCode();
151
152 }