1 package org.opentrafficsim.base.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) 2013-2016 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
12 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
13 * </p>
14 * $LastChangedDate: 2015-07-24 02:58:59 +0200 (Fri, 24 Jul 2015) $, @version $Revision: 1147 $, by $Author: averbraeck $,
15 * initial version May 7, 2016 <br>
16 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
17 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
18 * @author <a href="http://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 SortedMap<K, V> toMap();
29
30 /**
31 * Returns the comparator used to order the keys in this immutable map, or <tt>null</tt> if this immutable map uses the
32 * {@linkplain Comparable natural ordering} of its keys.
33 * @return the comparator used to order the keys in this immutable map, or <tt>null</tt> if this immutable map uses the
34 * natural ordering of its keys
35 */
36 Comparator<? super K> comparator();
37
38 /**
39 * Returns a view of the portion of this immutable map whose keys range from <tt>fromKey</tt>, inclusive, to
40 * <tt>toKey</tt>, exclusive. (If <tt>fromKey</tt> and <tt>toKey</tt> are equal, the returned immutable map is
41 * empty.)
42 * <p>
43 * The result of this method is a new, immutable sorted map.
44 * @param fromKey low endpoint (inclusive) of the returned immutable map
45 * @param toKey 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 <tt>fromKey</tt>,
47 * inclusive, to <tt>toKey</tt>, exclusive
48 * @throws ClassCastException if <tt>fromKey</tt> and <tt>toKey</tt> cannot be compared to one another using this
49 * immutable map's comparator (or, if the immutable map has no comparator, using natural ordering).
50 * Implementations may, but are not required to, throw this exception if <tt>fromKey</tt> or
51 * <tt>toKey</tt> cannot be compared to keys currently in the immutable map.
52 * @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt> is null and this immutable map does not permit
53 * null keys
54 * @throws IllegalArgumentException if <tt>fromKey</tt> is greater than <tt>toKey</tt>; or if this immutable map
55 * itself has a restricted range, and <tt>fromKey</tt> or <tt>toKey</tt> lies outside the bounds of the
56 * range
57 */
58 ImmutableSortedMap<K, V> subMap(K fromKey, K toKey);
59
60 /**
61 * Returns a view of the portion of this immutable map whose keys are strictly less than <tt>toKey</tt>. The
62 * returned immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this
63 * immutable map, and vice-versa. The returned immutable map supports all optional immutable map operations that this
64 * immutable map supports.
65 * <p>
66 * The result of this method is a new, immutable sorted map.
67 * @param toKey high endpoint (exclusive) of the returned immutable map
68 * @return a view of the portion of this immutable map whose keys are strictly less than <tt>toKey</tt>
69 * @throws ClassCastException if <tt>toKey</tt> is not compatible with this immutable map's comparator (or, if the
70 * immutable map has no comparator, if <tt>toKey</tt> does not implement {@link Comparable}).
71 * Implementations may, but are not required to, throw this exception if <tt>toKey</tt> cannot be compared
72 * to keys currently in the immutable map.
73 * @throws NullPointerException if <tt>toKey</tt> is null and this immutable map does not permit null keys
74 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <tt>toKey</tt> lies outside
75 * the bounds of the range
76 */
77 ImmutableSortedMap<K, V> headMap(K toKey);
78
79 /**
80 * Returns a view of the portion of this immutable map whose keys are greater than or equal to <tt>fromKey</tt>. The
81 * returned immutable map is backed by this immutable map, so changes in the returned immutable map are reflected in this
82 * immutable map, and vice-versa. The returned immutable map supports all optional immutable map operations that this
83 * immutable map supports.
84 * <p>
85 * The result of this method is a new, immutable sorted map.
86 * @param fromKey low endpoint (inclusive) of the returned immutable map
87 * @return a view of the portion of this immutable map whose keys are greater than or equal to <tt>fromKey</tt>
88 * @throws ClassCastException if <tt>fromKey</tt> is not compatible with this immutable map's comparator (or, if the
89 * immutable map has no comparator, if <tt>fromKey</tt> does not implement {@link Comparable}).
90 * Implementations may, but are not required to, throw this exception if <tt>fromKey</tt> cannot be compared
91 * to keys currently in the immutable map.
92 * @throws NullPointerException if <tt>fromKey</tt> is null and this immutable map does not permit null keys
93 * @throws IllegalArgumentException if this immutable map itself has a restricted range, and <tt>fromKey</tt> lies
94 * outside the bounds of the range
95 */
96 ImmutableSortedMap<K, V> tailMap(K fromKey);
97
98 /**
99 * Returns the first (lowest) key currently in this immutable map.
100 * @return the first (lowest) key currently in this immutable map
101 * @throws NoSuchElementException if this immutable map is empty
102 */
103 K firstKey();
104
105 /**
106 * Returns the last (highest) key currently in this immutable map.
107 * @return the last (highest) key currently in this immutable map
108 * @throws NoSuchElementException if this immutable map is empty
109 */
110 K lastKey();
111
112 /**
113 * Return an ImmutableSortedSet view of the keys contained in this immutable map.
114 * @return an ImmutableSortedSet view of the keys contained in this immutable map
115 */
116 ImmutableSortedSet<K> keySet();
117
118 /**
119 * Force to redefine equals for the implementations of immutable collection classes.
120 * @param obj the object to compare this collection with
121 * @return whether the objects are equal
122 */
123 boolean equals(final Object obj);
124
125 /**
126 * Force to redefine hashCode for the implementations of immutable collection classes.
127 * @return the calculated hashCode
128 */
129 int hashCode();
130
131 }