001/*
002 * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025package Torello.Java.ReadOnly;
026
027import Torello.Java.Additional.RemoveUnsupportedIterator;
028
029import java.util.SortedMap;
030import java.util.Comparator;
031import java.util.Map;
032import java.util.Set;
033
034/**
035 * Immutable variant of Java Collections Framework interface
036 * <CODE>java&#46;util&#46;SortedMap&lt;K, V&gt;</CODE>.
037 * 
038 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlySortedMap DATA-FILE-ID=INTERFACES>
039 * 
040 * @param <K> the type of keys maintained by this map
041 * @param <V> the type of mapped values
042 */
043@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_INTERFACE")
044public interface ReadOnlySortedMap<K, V> extends ReadOnlySequencedMap<K,V>
045{
046    // ********************************************************************************************
047    // ********************************************************************************************
048    // Original JDK Interface Methods
049    // ********************************************************************************************
050    // ********************************************************************************************
051
052
053    /**
054     * Returns the comparator used to order the keys in this map, or {@code null} if this map uses
055     * the {@code natural ordering} of its keys.
056     *
057     * @return the comparator used to order the keys in this map, or {@code null} if this map uses
058     * the natural ordering of its keys
059     */
060    Comparator<? super K> comparator();
061
062    /**
063     * Returns a view of the portion of this map whose keys range from {@code fromKey}, inclusive,
064     * to {@code toKey}, exclusive.  (If {@code fromKey} and {@code toKey} are equal, the returned
065     * map is empty.)  The returned map is backed by this map, so changes in the returned map are
066     * reflected in this map, and vice-versa.  The returned map supports all optional map
067     * operations that this map supports.
068     *
069     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
070     * key outside its range.
071     *
072     * @param fromKey low endpoint (inclusive) of the keys in the returned map
073     * @param toKey high endpoint (exclusive) of the keys in the returned map
074     * 
075     * @return a view of the portion of this map whose keys range from {@code fromKey}, inclusive,
076     * to {@code toKey}, exclusive
077     * 
078     * @throws ClassCastException if {@code fromKey} and {@code toKey} cannot be compared to one
079     * another using this map's comparator (or, if the map has no comparator, using natural
080     * ordering).  Implementations may, but are not required to, throw this exception if
081     * {@code fromKey} or {@code toKey} cannot be compared to keys currently in the map.
082     * 
083     * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this map does
084     * not permit null keys
085     * 
086     * @throws IllegalArgumentException if {@code fromKey} is greater than {@code toKey}; or if
087     * this map itself has a restricted range, and {@code fromKey} or {@code toKey} lies outside
088     * the bounds of the range
089     */
090    ReadOnlySortedMap<K,V> subMap(K fromKey, K toKey);
091
092    /**
093     * Returns a view of the portion of this map whose keys are strictly less than {@code toKey}.
094     * The returned map is backed by this map, so changes in the returned map are reflected in this
095     * map, and vice-versa.  The returned map supports all optional map operations that this map
096     * supports.
097     *
098     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
099     * key outside its range.
100     *
101     * @param toKey high endpoint (exclusive) of the keys in the returned map
102     * @return a view of the portion of this map whose keys are strictly less than {@code toKey}
103     * 
104     * @throws ClassCastException if {@code toKey} is not compatible with this map's comparator
105     * (or, if the map has no comparator, if {@code toKey} does not implement {@link Comparable}).
106     * Implementations may, but are not required to, throw this exception if {@code toKey} cannot
107     * be compared to keys currently in the map.
108     * 
109     * @throws NullPointerException if {@code toKey} is null and this map does not permit null keys
110     * 
111     * @throws IllegalArgumentException if this map itself has a restricted range, and
112     * {@code toKey} lies outside the bounds of the range
113     */
114    ReadOnlySortedMap<K,V> headMap(K toKey);
115
116    /**
117     * Returns a view of the portion of this map whose keys are greater than or equal to
118     * {@code fromKey}.  The returned map is backed by this map, so changes in the returned map are
119     * reflected in this map, and vice-versa.  The returned map supports all optional map
120     * operations that this map supports.
121     *
122     * <BR /><BR />The returned map will throw an {@code IllegalArgumentException} on an attempt to insert a
123     * key outside its range.
124     *
125     * @param fromKey low endpoint (inclusive) of the keys in the returned map
126     * 
127     * @return a view of the portion of this map whose keys are greater than or equal to
128     * {@code fromKey}
129     * 
130     * @throws ClassCastException if {@code fromKey} is not compatible with this map's comparator
131     * (or, if the map has no comparator, if {@code fromKey} does not implement
132     * {@code Comparable}).  Implementations may, but are not required to, throw this exception if
133     * {@code fromKey} cannot be compared to keys currently in the map.
134     * 
135     * @throws NullPointerException if {@code fromKey} is null and this map does not permit null
136     * keys
137     * 
138     * @throws IllegalArgumentException if this map itself has a restricted range, and
139     * {@code fromKey} lies outside the bounds of the range
140     */
141    ReadOnlySortedMap<K,V> tailMap(K fromKey);
142
143    /**
144     * Returns the first (lowest) key currently in this map.
145     * @return the first (lowest) key currently in this map
146     * @throws NoSuchElementException if this map is empty
147     */
148    K firstKey();
149
150    /**
151     * Returns the last (highest) key currently in this map.
152     * @return the last (highest) key currently in this map
153     * @throws NoSuchElementException if this map is empty
154     */
155    K lastKey();
156
157    /**
158     * Returns a {@link ReadOnlySet} view of the keys contained in this map.  The set's iterator
159     * returns the keys in ascending order.
160     * 
161     * @return a set view of the keys contained in this map, sorted in ascending order
162     */
163    ReadOnlySet<K> keySet();
164
165    /**
166     * Returns a {@link ReadOnlyCollection} view of the values contained in this map.  The
167     * collection's iterator returns the values in ascending order of the corresponding keys.
168     * 
169     * @return a collection view of the values contained in this map, sorted in ascending key order
170     */
171    ReadOnlyCollection<V> values();
172
173    /**
174     * Returns a {@link ReadOnlySet} view of the mappings contained in this map.  The set's
175     * iterator returns the entries in ascending key order.
176     * 
177     * @return a set view of the mappings contained in this map, sorted in ascending key order
178     */
179    ReadOnlySet<ReadOnlyMap.Entry<K, V>> entrySet();
180
181    /**
182     * {@inheritDoc}
183     *
184     * @implSpec
185     * The implementation in this interface returns a reverse-ordered {@code ReadOnlySortedMap}
186     * view. The {@code reversed()} method of the view returns a reference to this
187     * {@code ReadOnlySortedMap}. Other operations on the view are implemented via calls to public
188     * methods on this {@code ReadOnlySortedMap}. The exact relationship between calls on the view
189     * and calls on this {@code ReadOnlySortedMap} is unspecified.  However, order-sensitive
190     * operations generally delegate to the appropriate method with the opposite orientation. For
191     * example, calling {@code firstEntry} on the view results in a call to {@code lastEntry} on
192     * this SortedMap.
193     *
194     * @return a reverse-ordered view of this map, as a {@code ReadOnlySortedMap}
195     */
196    default ReadOnlySortedMap<K, V> reversed()
197    {
198        return JDKReverseOrderSortedMapView.of(this);
199        // throw new UnsupportedOperationException();
200    }
201}