1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

/*
 * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package Torello.Java.ReadOnly;

import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.SortedMap;
import java.util.Comparator;
import java.util.Map;
import java.util.Set;

/**
 * Immutable variant of Java Collections Framework interface
 * <CODE>java&#46;util&#46;SortedMap&lt;K, V&gt;</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlySortedMap DATA-FILE-ID=INTERFACES>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE")
public interface ReadOnlySortedMap<K, V> extends ReadOnlySequencedMap<K,V>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Interface Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the comparator used to order the keys in this map, or {@code null} if this map uses
     * the {@code natural ordering} of its keys.
     *
     * @return the comparator used to order the keys in this map, or {@code null} if this map uses
     * the natural ordering of its keys
     */
    Comparator<? super K> comparator();

    /**
     * Returns a view of the portion of this map whose keys range from {@code fromKey}, inclusive,
     * to {@code toKey}, exclusive.  (If {@code fromKey} and {@code toKey} are equal, the returned
     * map is empty.)  The returned map is backed by this map, so changes in the returned map are
     * reflected in this map, and vice-versa.  The returned map supports all optional map
     * operations that this map supports.
     *
     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
     * key outside its range.
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * 
     * @return a view of the portion of this map whose keys range from {@code fromKey}, inclusive,
     * to {@code toKey}, exclusive
     * 
     * @throws ClassCastException if {@code fromKey} and {@code toKey} cannot be compared to one
     * another using this map's comparator (or, if the map has no comparator, using natural
     * ordering).  Implementations may, but are not required to, throw this exception if
     * {@code fromKey} or {@code toKey} cannot be compared to keys currently in the map.
     * 
     * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this map does
     * not permit null keys
     * 
     * @throws IllegalArgumentException if {@code fromKey} is greater than {@code toKey}; or if
     * this map itself has a restricted range, and {@code fromKey} or {@code toKey} lies outside
     * the bounds of the range
     */
    ReadOnlySortedMap<K,V> subMap(K fromKey, K toKey);

    /**
     * Returns a view of the portion of this map whose keys are strictly less than {@code toKey}.
     * The returned map is backed by this map, so changes in the returned map are reflected in this
     * map, and vice-versa.  The returned map supports all optional map operations that this map
     * supports.
     *
     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
     * key outside its range.
     *
     * @param toKey high endpoint (exclusive) of the keys in the returned map
     * @return a view of the portion of this map whose keys are strictly less than {@code toKey}
     * 
     * @throws ClassCastException if {@code toKey} is not compatible with this map's comparator
     * (or, if the map has no comparator, if {@code toKey} does not implement {@link Comparable}).
     * Implementations may, but are not required to, throw this exception if {@code toKey} cannot
     * be compared to keys currently in the map.
     * 
     * @throws NullPointerException if {@code toKey} is null and this map does not permit null keys
     * 
     * @throws IllegalArgumentException if this map itself has a restricted range, and
     * {@code toKey} lies outside the bounds of the range
     */
    ReadOnlySortedMap<K,V> headMap(K toKey);

    /**
     * Returns a view of the portion of this map whose keys are greater than or equal to
     * {@code fromKey}.  The returned map is backed by this map, so changes in the returned map are
     * reflected in this map, and vice-versa.  The returned map supports all optional map
     * operations that this map supports.
     *
     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
     * key outside its range.
     *
     * @param fromKey low endpoint (inclusive) of the keys in the returned map
     * 
     * @return a view of the portion of this map whose keys are greater than or equal to
     * {@code fromKey}
     * 
     * @throws ClassCastException if {@code fromKey} is not compatible with this map's comparator
     * (or, if the map has no comparator, if {@code fromKey} does not implement
     * {@code Comparable}).  Implementations may, but are not required to, throw this exception if
     * {@code fromKey} cannot be compared to keys currently in the map.
     * 
     * @throws NullPointerException if {@code fromKey} is null and this map does not permit null
     * keys
     * 
     * @throws IllegalArgumentException if this map itself has a restricted range, and
     * {@code fromKey} lies outside the bounds of the range
     */
    ReadOnlySortedMap<K,V> tailMap(K fromKey);

    /**
     * Returns the first (lowest) key currently in this map.
     * @return the first (lowest) key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    K firstKey();

    /**
     * Returns the last (highest) key currently in this map.
     * @return the last (highest) key currently in this map
     * @throws NoSuchElementException if this map is empty
     */
    K lastKey();

    /**
     * Returns a {@link ReadOnlySet} view of the keys contained in this map.  The set's iterator
     * returns the keys in ascending order.
     * 
     * @return a set view of the keys contained in this map, sorted in ascending order
     */
    ReadOnlySet<K> keySet();

    /**
     * Returns a {@link ReadOnlyCollection} view of the values contained in this map.  The
     * collection's iterator returns the values in ascending order of the corresponding keys.
     * 
     * @return a collection view of the values contained in this map, sorted in ascending key order
     */
    ReadOnlyCollection<V> values();

    /**
     * Returns a {@link ReadOnlySet} view of the mappings contained in this map.  The set's
     * iterator returns the entries in ascending key order.
     * 
     * @return a set view of the mappings contained in this map, sorted in ascending key order
     */
    ReadOnlySet<ReadOnlyMap.Entry<K, V>> entrySet();

    /**
     * {@inheritDoc}
     *
     * @implSpec
     * The implementation in this interface returns a reverse-ordered {@code ReadOnlySortedMap}
     * view. The {@code reversed()} method of the view returns a reference to this
     * {@code ReadOnlySortedMap}. Other operations on the view are implemented via calls to public
     * methods on this {@code ReadOnlySortedMap}. The exact relationship between calls on the view
     * and calls on this {@code ReadOnlySortedMap} is unspecified.  However, order-sensitive
     * operations generally delegate to the appropriate method with the opposite orientation. For
     * example, calling {@code firstEntry} on the view results in a call to {@code lastEntry} on
     * this SortedMap.
     *
     * @return a reverse-ordered view of this map, as a {@code ReadOnlySortedMap}
     */
    default ReadOnlySortedMap<K, V> reversed()
    {
        return JDKReverseOrderSortedMapView.of(this);
        // throw new UnsupportedOperationException();
    }
}