/*
 * 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.
 */

/*
 * This file is available under and governed by the GNU General Public
 * License version 2 only, as published by the Free Software Foundation.
 * However, the following notice accompanied the original version of this
 * file:
 *
 * Written by Doug Lea and Josh Bloch with assistance from members of JCP
 * JSR-166 Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */
package Torello.Java.ReadOnly;

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

/**
 * Immutable variant of Java Collectionds Framework interface
 * <CODE>java&#46;util&#46;NavigableMap&lt;K, V&gt;</CODE>.
 * 
 * <EMBED CLASS='external-html' DATA-JDK=ReadOnlyNavigableMap 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 ReadOnlyNavigableMap<K, V> extends ReadOnlySortedMap<K,V>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Interface Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a key-value mapping associated with the greatest key strictly less than the given
     * key, or {@code null} if there is no such key.
     *
     * @param key the key
     * 
     * @return an entry with the greatest key less than {@code key}, or {@code null} if there is no
     * such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    ReadOnlyMap.Entry<K,V> lowerEntry(K key);

    /**
     * Returns the greatest key strictly less than the given key, or {@code null} if there is no
     * such key.
     *
     * @param key the key
     * @return the greatest key less than {@code key}, or {@code null} if there is no such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    K lowerKey(K key);

    /**
     * Returns a key-value mapping associated with the greatest key less than or equal to the given
     * key, or {@code null} if there is no such key.
     *
     * @param key the key
     * 
     * @return an entry with the greatest key less than or equal to {@code key}, or {@code null} if
     * there is no such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    ReadOnlyMap.Entry<K,V> floorEntry(K key);

    /**
     * Returns the greatest key less than or equal to the given key, or {@code null} if there is no
     * such key.
     *
     * @param key the key
     * 
     * @return the greatest key less than or equal to {@code key}, or {@code null} if there is no
     * such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    K floorKey(K key);

    /**
     * Returns a key-value mapping associated with the least key greater than or equal to the given
     * key, or {@code null} if there is no such key.
     *
     * @param key the key
     * 
     * @return an entry with the least key greater than or equal to {@code key}, or {@code null} if
     * there is no such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently in
     * the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    ReadOnlyMap.Entry<K,V> ceilingEntry(K key);

    /**
     * Returns the least key greater than or equal to the given key, or {@code null} if there is no
     * such key.
     *
     * @param key the key
     * 
     * @return the least key greater than or equal to {@code key}, or {@code null} if there is no
     * such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    K ceilingKey(K key);

    /**
     * Returns a key-value mapping associated with the least key strictly greater than the given
     * key, or {@code null} if there is no such key.
     *
     * @param key the key
     * 
     * @return an entry with the least key greater than {@code key}, or {@code null} if there is no
     * such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    ReadOnlyMap.Entry<K,V> higherEntry(K key);

    /**
     * Returns the least key strictly greater than the given key, or {@code null} if there is no
     * such key.
     *
     * @param key the key
     * 
     * @return the least key greater than {@code key}, or {@code null} if there is no such key
     * 
     * @throws ClassCastException if the specified key cannot be compared with the keys currently
     * in the map
     * 
     * @throws NullPointerException if the specified key is null and this map does not permit null
     * keys
     */
    K higherKey(K key);

    /**
     * Returns a key-value mapping associated with the least key in this map, or {@code null} if
     * the map is empty.
     *
     * @return an entry with the least key, or {@code null} if this map is empty
     */
    ReadOnlyMap.Entry<K,V> firstEntry();

    /**
     * Returns a key-value mapping associated with the greatest key in this map, or {@code null} if
     * the map is empty.
     *
     * @return an entry with the greatest key, or {@code null} if this map is empty
     */
    ReadOnlyMap.Entry<K,V> lastEntry();

    /**
     * Returns a reverse order view of the mappings contained in this map.  
     * @return a reverse order view of this map
     */
    ReadOnlyNavigableMap<K,V> descendingMap();

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

    /**
     * Returns a reverse order {@link ReadOnlyNavigableSet} view of the keys contained in this map.
     * The set's iterator returns the keys in descending order.
     * 
     * @return a reverse order navigable set view of the keys in this map
     */
    ReadOnlyNavigableSet<K> descendingKeySet();

    /**
     * Returns a view of the portion of this map whose keys range from {@code fromKey} to
     * {@code toKey}.  If {@code fromKey} and {@code toKey} are equal, the returned map is empty
     * unless {@code fromInclusive} and {@code toInclusive} are both true.
     * 
     * <BR /><BR />The returned map supports all optional map operations that this map supports.
     *
     * @param fromKey low endpoint of the keys in the returned map
     * @param fromInclusive {@code TRUE} if the low endpoint is to be included in the returned view
     * @param toKey high endpoint of the keys in the returned map
     * @param toInclusive {@code TRUE} if the high endpoint is to be included in the returned view
     * 
     * @return a view of the portion of this map whose keys range from {@code fromKey} to
     * {@code toKey}
     * 
     * @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
     */
    ReadOnlyNavigableMap<K,V> subMap(
            K fromKey, boolean fromInclusive,
            K toKey,   boolean toInclusive
        );

    /**
     * Returns a view of the portion of this map whose keys are less than (or
     * equal to, if {@code inclusive} is true) {@code toKey}.
     * 
     * The returned map supports all optional map operations that this map supports.
     * 
     * @param toKey high endpoint of the keys in the returned map
     * @param inclusive {@code TRUE} if the high endpoint is to be included in the returned view
     * 
     * @return a view of the portion of this map whose keys are less than (or equal to, if
     * {@code inclusive} is true) {@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
     */
    ReadOnlyNavigableMap<K,V> headMap(K toKey, boolean inclusive);

    /**
     * Returns a view of the portion of this map whose keys are greater than (or equal to, if
     * {@code inclusive} is true) {@code fromKey}.
     *
     * The returned map supports all optional map operations that this map supports.
     *
     * @param fromKey low endpoint of the keys in the returned map
     * @param inclusive {@code TRUE} if the low endpoint is to be included in the returned view
     * 
     * @return a view of the portion of this map whose keys are greater than (or equal to, if
     * {@code inclusive} is true) {@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
     * {@link 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
     */
    ReadOnlyNavigableMap<K,V> tailMap(K fromKey, boolean inclusive);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code subMap(fromKey, true, toKey, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedMap<K,V> subMap(K fromKey, K toKey);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code headMap(toKey, false)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedMap<K,V> headMap(K toKey);

    /**
     * {@inheritDoc}
     *
     * <BR /><BR />Equivalent to {@code tailMap(fromKey, true)}.
     *
     * @throws ClassCastException       {@inheritDoc}
     * @throws NullPointerException     {@inheritDoc}
     * @throws IllegalArgumentException {@inheritDoc}
     */
    ReadOnlySortedMap<K,V> tailMap(K fromKey);

    /**
     * {@inheritDoc}
     * <BR /><BR />
     * This method is equivalent to {@link #descendingMap descendingMap}.
     *
     * @implSpec
     * The implementation in this interface returns the result of calling the
     * {@code descendingMap} method.
     *
     * @return a reverse-ordered view of this map, as a {@code NavigableMap}
     */
    default ReadOnlyNavigableMap<K, V> reversed()
    { return this.descendingMap(); }
}