/*
 * Copyright (c) 1997, 2018, 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 java.io.Serializable;

import java.util.*;

import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Consumer;
import java.util.function.Predicate;
import java.util.function.Function;

import Torello.Java.ReadOnly.ROTreeMapBuilder;
import Torello.Java.Additional.Tuple2;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;TreeMap</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=TreeMap>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * 
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
@SuppressWarnings("unchecked")
public class ReadOnlyTreeMap<K, V>
    // extends AbstractReadOnlyMap<K, V>
    implements ReadOnlyNavigableMap<K, V>, java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // Minor Optimization where new TreeMap's that have no contents always re-use this static
    // instance.  Since this instance is completely empty, the Raw-Types things is irrelevant.

    @SuppressWarnings("rawtypes")
    private static final TreeMap EMPTY_TREE_MAP = new TreeMap();

    // Singleton & Empty ReadOnlyTreeMap, Uses the "Supplier Constructor"
    @SuppressWarnings("rawtypes")
    private static final ReadOnlyTreeMap EMPTY_READONLY_TREE_MAP =
        new ReadOnlyTreeMap(EMPTY_TREE_MAP);

    // The actual TreeMap used by this instance.
    private final TreeMap<K, V> treeMap;

    // TRUE     => This was built using the class ROTreeMapBuilder
    // FALSE    => This was built using the clone() of a standard java.util.TreeMap constructor

    private final boolean fromBuilderOrTreeMap;

    // Mimics the C++ Keyword/Concept of "Friend Class".   Is "Friends With" ROTreeMapBuilder
    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();


    // ********************************************************************************************
    // ********************************************************************************************
    // Builder, Acess-Badge Constructor - and Static "Empty" getter (which is used by the builder)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an empty, <B STYLE='color: red;'>singleton</B>, instance of {@code ReadOnlyTreeMap}.
     * @param <X> Returned {@link ReadOnlyMap}'s Key-Type.
     * @param <Y> Returned {@link ReadOnlyMap}'s Value-Type.  
     * 
     * @return An empty map.  Since this map is both empty &amp; read-only, a raw-type singleton 
     * will suffice for all operations offered by this clas.
     */
    public static <X, Y> ReadOnlyTreeMap<X, Y> emptyROTM()
    { return (ReadOnlyTreeMap<X, Y>) EMPTY_READONLY_TREE_MAP; }

    // To all the readers out there following along: The "AccessBadge" thing is just a slightly
    // wimpier substitute for the C++ keyword / concept 'friend' or "Friend Class".  It means this
    // constructor is (for all intents and purposes) a private-constructor, except for the class
    // ROTreeMapBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyTreeMap(ROTreeMapBuilder<K, V> rotmb, ROTreeMapBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        this.fromBuilderOrTreeMap = true;
        this.treeMap = rotmb;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Modified-Original Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Copies the contents of parameter {@code 'map'}, and saves saves it, thereby guaranteeing
     * {@code 'this'} instance is Read-Only and fully-shielded from outside modification.
     * 
     * @param map The {@code Map} to be copied into {@code 'this'} instance internal and private
     * {@code 'treeMap'} field.
     */
    public ReadOnlyTreeMap(Map<K, V> map)
    {
        this.fromBuilderOrTreeMap = false;

        this.treeMap = (map.size() == 0)
            ? ((TreeMap<K, V>) EMPTY_TREE_MAP)
            : new TreeMap<K, V>(map);
    }

    /**
     * If only a small amount of processing needs to be done on the contents of some Java
     * Map, and using an entire Builder-Class seems disproportionately complex - <I>this
     * constructor can convert any Java {@code Map} into a {@code ReadOnlyTreeMap}, using
     * a simple {@code 'mapTranslator'}</I>.
     * 
     * @param <X> The Key-Type of the User-Provided {@code Map}.
     * @param <Y> The Value-Type of the User-Provided {@code Map}.
     * 
     * @param refHolder This must a non-null instance of {@link Tuple2}.  The provided
     * {@code Consumer} is just that, a {@code 'Consumer'} rather than a {@code 'Function'}, since
     * the results of each translation must be assigned to the values inside this tuple in order
     * for them to be inserted into this {@code ReadOnlyTreeMap}.
     * 
     * @param map Any Java {@code Map}.
     * 
     * @param mapTranslator A function for mapping the iterated elements of Map-Types {@code 'X'}
     * and {@code 'Y'}, into the actual {@code TreeMap's} Key-Type {@code 'K'}, and Value-Type
     * {@code 'V'}.  The results of this translation must be placed into the fields inside
     * {@code 'refHolder'}.
     * 
     * <BR /><BR />If this parameter is passed null, this method will throw a
     * {@code NullPointerException}.
     * 
     * @param filter An optional filter that can be used to prevent &amp; prohibit any chosen
     * elements from input {@code 'map'} from being inserted into {@code 'this'}
     * {@code ReadOnlyTreeMap}.
     * 
     * <BR /><BR />This parameter may be passed null, and if it is, it will be silently ignored, 
     * and all entries present inside {@code 'map'} will be processed and inserted into
     * {@code 'this'}
     * 
     * @param comparator <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     * 
     * @throws NullPointerException if either parameter {@code 'i'} or parameter 
     * {@code 'mapTranslator'} is passed null.
     */
    public <X, Y> ReadOnlyTreeMap(
            Tuple2<K, V>                refHolder,
            Map<X, Y>                   map,
            Consumer<Map.Entry<X, Y>>   mapTranslator,
            Predicate<Map.Entry<X, Y>>  filter,
            Comparator<? super K>       comparator
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(mapTranslator, ROHelpers.NULL_MSG + "'mapTranslator'");

        fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = (comparator != null)
            ? new TreeMap<>(comparator)
            : new TreeMap<>();

        if (filter == null)

            for (Map.Entry<X, Y> entry : map.entrySet())
            {
                mapTranslator.accept(entry);
                treeMap.put(refHolder.a, refHolder.b);
            }

        else for (Map.Entry<X, Y> entry : map.entrySet())
        {
            if (! filter.test(entry)) continue;
            mapTranslator.accept(entry);
            treeMap.put(refHolder.a, refHolder.b);
        }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // New Constructors, January 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an instance of {@code ReadOnlyTreeMap} that contains the keys present in
     * parameter {@code 'keys'}, and values generated by {@code 'valueMapper'} - using each of the
     * {@code 'keys'} as input.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param keys          Any Java {@code Iterable} instance.
     * @param valueMapper   A user provided function to compute a map value, based on a map key.
     * @param filter        <EMBED CLASS='external-html' DATA-FILE-ID=MAP_ITERABLE_FILTER>
     * @param comparator    <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     *  
     * @throws NullPointerException if either {@code 'keys'} or {@code 'valueMapper'} are passed
     * null.
     */
    public ReadOnlyTreeMap(
            Iterable<? extends K>               keys,
            Function<? super K, ? extends V>    valueMapper,
            Predicate<? super K>                filter,
            Comparator<? super K>               comparator
        )
    {
        Objects.requireNonNull(keys, ROHelpers.NULL_MSG + "'keys'");
        Objects.requireNonNull(valueMapper, ROHelpers.NULL_MSG + "'valueMapper'");

        fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = (comparator != null)
            ? new TreeMap<>(comparator)
            : new TreeMap<>();

        if (filter == null)
            for (K key : keys)
                treeMap.put(key, valueMapper.apply(key));

        else
            for (K key : keys)
                if (filter.test(key))
                    treeMap.put(key, valueMapper.apply(key));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }

    /**
     * Constructs an instance of {@code ReadOnlyTreeMap} that has been populated by the Key-Value
     * Pairs left in {@code 'refHolder'} by each invocation of the {@code Runnable} parameter
     * {@code 'computeNextEntry'}.  Key-Value Pairs are inserted until an invocation of the 
     * {@code Runnable} leaves null in {@code refHolder.a} and {@code refHolder.b}
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param refHolder         <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry  <EMBED CLASS='external-html' DATA-FILE-ID=COMPUTE_NEXT_RUN>
     * @param comparator        <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     *  
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'} are
     * passed null.
     */
    public ReadOnlyTreeMap(
            Tuple2<K, V>            refHolder,
            Runnable                computeNextEntry,
            Comparator<? super K>   comparator
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = (comparator != null)
            ? new TreeMap<>(comparator)
            : new TreeMap<>();

        do
        {
            computeNextEntry.run();
            if ((refHolder.a == null) && (refHolder.b == null)) break;
            treeMap.put(refHolder.a, refHolder.b);
        }
        while (true);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }

    /**
     * Populates an instance of {@code ReadOnlyTreeMap} by iterating the input {@code 'source'}
     * iterable, and passing each value returned by that {@code Iterator} to the
     * {@code 'computeNextEntry'} Java {@code Consumer}.
     * 
     * <BR /><BR />It is the programmer's responsibility to properly place each Key-Value Pair 
     * that is intending to be inserted into the final {@code Map} instance into the
     * {@code 'refHolder'} instance.  After each invocation of {@code 'computeNextEntry'}, this 
     * constructor's logic will retrieve the values within {@code 'refHolder.a'} and
     * {@code 'refHolder.b'} and insert them into this instance internal {@code TreeMap}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=LOOK_AT_IT>
     * 
     * @param <X>               The type of the elements inside {@code 'source'}
     * @param source            Any Java {@code Iterable} instance.
     * @param refHolder         <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry  <EMBED CLASS='external-html' DATA-FILE-ID=COMPUTE_NEXT_CONS>
     * @param filter            <EMBED CLASS='external-html' DATA-FILE-ID=MAP_ITERABLE_FILTER>
     * @param comparator        <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     * 
     * @throws NullPointerException if either {@code 'refHolder'}, {@code 'computeNextEntry'} or
     * {@code 'source'} are passed null.
     */
    public <X> ReadOnlyTreeMap(
            Iterable<X>             source,
            Tuple2<K, V>            refHolder,
            Consumer<? super X>     computeNextEntry,
            Predicate<? super X>    filter,
            Comparator<? super K>   comparator
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = (comparator != null)
            ? new TreeMap<>(comparator)
            : new TreeMap<>();

        X x; // temp var
        Iterator<X> iter = source.iterator();

        if (filter == null)

            while (iter.hasNext())
            {
                computeNextEntry.accept(iter.next());
                treeMap.put(refHolder.a, refHolder.b);
            }

        else

            while (iter.hasNext())
                if (filter.test(x = iter.next()))
                {
                    computeNextEntry.accept(x);
                    treeMap.put(refHolder.a, refHolder.b);
                }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Array Constructors, March 2024
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieves elements from the VarArgs Generic-Array parameter {@code 'elements'}, and
     * subsequently invokes the {@code 'computeNextEntry'} processor to populate this
     * {@code ReadOnlyTreeMap}.
     * 
     * @param <X>                  The type of array parameter {@code 'elements'}
     * @param refHolder            <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param computeNextEntry     <EMBED CLASS='external-html' DATA-FILE-ID=ARR_COMPUTE_NEXT_CONS>
     * @param filter               <EMBED CLASS='external-html' DATA-FILE-ID=MAP_ARRAY_FILTER>
     * @param comparator           <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     * @param elements             Any Generic VarArgs-Array
     * @throws ClassCastException  <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * 
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'}
     * are passed null
     */
    public <X> ReadOnlyTreeMap(
            Tuple2<K, V>            refHolder,
            Consumer<? super X>     computeNextEntry,
            Predicate<? super X>    filter,
            Comparator<? super K>   comparator,
            X...                    elements
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        this.fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = (comparator != null) ? new TreeMap<>(comparator) : new TreeMap<>();

        if (filter == null) for (X e : elements)
        {
            computeNextEntry.accept(e);
            treeMap.put(refHolder.a, refHolder.b);
        }

        else for (X x : elements) if (filter.test(x))
        {
            computeNextEntry.accept(x);
            treeMap.put(refHolder.a, refHolder.b);
        }

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }

    /**
     * Retrieves elements from the Java Primitive-Array parameter {@code 'primitiveArray'}, and
     * subsequently invokes the {@code 'computeNextEntry'} processor to populate this
     * {@code ReadOnlyTreeMap}.
     * 
     * @param filter               <EMBED CLASS='external-html' DATA-FILE-ID=PRED_FILT_PRIM>
     * @param computeNextEntry     <EMBED CLASS='external-html' DATA-FILE-ID=ARR_COMPUTE_NEXT_CONS>
     * @param refHolder            <EMBED CLASS='external-html' DATA-FILE-ID=REF_HOLDER>
     * @param comparator           <EMBED CLASS='external-html' DATA-FILE-ID=COMPARATOR>
     * @param primitiveArray       Any Java Primitive-Array
     * @throws ClassCastException  <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * 
     * @throws NullPointerException if either {@code 'refHolder'} or {@code 'computeNextEntry'}
     * are passed null
     * 
     */
    public <X> ReadOnlyTreeMap(
            Predicate<?>            filter,
            Consumer<?>             computeNextEntry,
            Tuple2<K, V>            refHolder,
            Comparator<? super K>   comparator,
            Object                  primitiveArray
        )
    {
        Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
        Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

        this.fromBuilderOrTreeMap = false;

        TreeMap<K, V> treeMap = ROHelpers.buildROMap(
            primitiveArray,
            (int arrayLen) -> (comparator != null) ? new TreeMap<>(comparator) : new TreeMap<>(),
            filter,
            refHolder,
            computeNextEntry
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.treeMap = (treeMap.size() == 0) ? ((TreeMap<K, V>) EMPTY_TREE_MAP) : treeMap;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert to java.util Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clone's {@code 'this'} instance internal {@code TreeMap<K, V>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=TreeMap DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance internal
     * {@code TreeMap<K, V>} data-structure.
     */
    public TreeMap<K, V> cloneToTreeMap()
    {
        if (! fromBuilderOrTreeMap) return (TreeMap<K, V>) this.treeMap.clone();

        TreeMap<K, V> ret = new TreeMap<K, V>();

        for (Map.Entry<K, V> e :
            ((ROTreeMapBuilder<K, V>) this.treeMap)._entrySet(friendClassBadge))

            ret.put(e.getKey(), e.getValue());

        return ret; 
    }

    /**
     * Invokes {@code java.util.Collections.unmodifiableMap} on the internal {@code TreeMap}.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=Map DATA-FILE-ID=WRAP_TO_IMMUTABLE>
     * 
     * @return A {@code Map} which adheres to the JDK interface {@code java.util.Map}, but throws
     * an {@code UnsupportedOperationException} if a user attempts to invoke a Mutator-Method on
     * the returned instance.
     */
    public Map<K, V> wrapToImmutableMap()
    { return Collections.unmodifiableMap(this.treeMap); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods, java.util.TreeMap
    // ********************************************************************************************
    // ********************************************************************************************
    

    /**
     * Returns the number of key-value mappings in this map.
     * @return the number of key-value mappings in this map
     */
    public int size()
    { return this.treeMap.size(); }

    /**
     * Returns {@code TRUE} if this map contains a mapping for the specified key.
     *
     * @param key key whose presence in this map is to be tested
     * @return {@code TRUE} if this map contains a mapping for the specified 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 uses natural
     * ordering, or its comparator does not permit null keys
     */
    public boolean containsKey(Object key)
    { return this.treeMap.containsKey(key); }

    /**
     * Returns {@code TRUE} if this map maps one or more keys to the specified value.  More
     * formally, returns {@code TRUE} if and only if this map contains at least one mapping to a
     * value {@code v} such that {@code (value==null ? v==null : value.equals(v))}.
     *
     * @param value value whose presence in this map is to be tested
     * @return {@code TRUE} if a mapping to {@code value} exists; {@code FALSE} otherwise
     */
    public boolean containsValue(Object value)
    { return this.treeMap.containsValue(value); }

    /**
     * Returns the value to which the specified key is mapped, or {@code null} if this map contains
     * no mapping for the key.
     *
     * <BR /><BR />More formally, if this map contains a mapping from a key {@code k} to a value
     * {@code v} such that {@code key} compares equal to {@code k} according to the map's ordering,
     * then this method returns {@code v}; otherwise it returns {@code null}.  (There can be at
     * most one such mapping.)
     *
     * <BR /><BR />A return value of {@code null} does not <em>necessarily</em> indicate that the
     * map contains no mapping for the key; it's also possible that the map explicitly maps the key
     * to {@code null}.  The {@link #containsKey containsKey} operation may be used to distinguish
     * these two cases.
     *
     * @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 uses natural
     * ordering, or its comparator does not permit null keys
     */
    public V get(Object key)
    { return this.treeMap.get(key); }

    public Comparator<? super K> comparator()
    { return this.treeMap.comparator(); }

    /** @throws NoSuchElementException {@inheritDoc} */
    public K firstKey()
    { return this.treeMap.firstKey(); }

    /** @throws NoSuchElementException {@inheritDoc} */
    public K lastKey()
    { return this.treeMap.lastKey(); }

    public ReadOnlyMap.Entry<K,V> firstEntry()
    { return new EntryImpl<>(this.treeMap.firstEntry()); }

    public ReadOnlyMap.Entry<K,V> lastEntry()
    { return new EntryImpl<>(this.treeMap.lastEntry()); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public ReadOnlyMap.Entry<K,V> lowerEntry(K key)
    { return new EntryImpl<>(this.treeMap.lowerEntry(key)); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public K lowerKey(K key)
    { return this.treeMap.lowerKey(key); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public ReadOnlyMap.Entry<K,V> floorEntry(K key)
    { return new EntryImpl<>(this.treeMap.floorEntry(key)); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public K floorKey(K key)
    { return this.treeMap.floorKey(key); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public ReadOnlyMap.Entry<K,V> ceilingEntry(K key)
    { return new EntryImpl<>(this.treeMap.ceilingEntry(key)); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public K ceilingKey(K key)
    { return this.treeMap.ceilingKey(key); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public ReadOnlyMap.Entry<K,V> higherEntry(K key)
    { return new EntryImpl<>(this.treeMap.higherEntry(key)); }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if the specified key is null and this map uses natural
     * ordering, or its comparator does not permit null keys
     */
    public K higherKey(K key)
    { return this.treeMap.higherKey(key); }

    /** Returns a {@link ReadOnlySet} view of the keys contained in this map. */
    public ReadOnlySet<K> keySet()
    {
        return InterfaceBuilder.toReadOnlySet(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._keySet(friendClassBadge)
                : this.treeMap.keySet()
        );
    }

    public ReadOnlyNavigableSet<K> navigableKeySet()
    {
        return InterfaceBuilder.toReadOnlyNavigableSet(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._navigableKeySet(friendClassBadge)
                : this.treeMap.navigableKeySet()
        );
    }

    public ReadOnlyNavigableSet<K> descendingKeySet()
    {
        return InterfaceBuilder.toReadOnlyNavigableSet(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._descendingKeySet(friendClassBadge)
                : this.treeMap.descendingKeySet()
        );
    }

    /** Returns a {@link ReadOnlyCollection} view of the values contained in this map. */
    public ReadOnlyCollection<V> values()
    {
        return InterfaceBuilder.toReadOnlyCollection(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._values(friendClassBadge)
                : this.treeMap.values()
        );
    }

    /**
     * Returns a {@link ReadOnlySet} view of the mappings contained in this map.
     * 
     * @return At the moment, a {@link ReadOnlyTreeSet} is arbitrarily used for the type of the
     * returned instance
     */
    public ReadOnlySet<ReadOnlyMap.Entry<K, V>> entrySet()
    {
        return ROHelpers.toReadOnlyEntrySet(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._entrySet(friendClassBadge)
                : this.treeMap.entrySet()
        );
    }

    public ReadOnlyNavigableMap<K, V> descendingMap()
    {
        return InterfaceBuilder.toReadOnlyNavigableMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._descendingMap(friendClassBadge)
                : this.treeMap.descendingMap()
        );
    }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this map uses
     * natural ordering, or its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlyNavigableMap<K,V> subMap(
            K fromKey, boolean fromInclusive,
            K toKey,   boolean toInclusive
        )
    {
        return InterfaceBuilder.toReadOnlyNavigableMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._subMap
                    (fromKey, fromInclusive, toKey, toInclusive, friendClassBadge)
                : this.treeMap.subMap(fromKey, fromInclusive, toKey, toInclusive)
        );
    }

    /**
     * @throws ClassCastExceptionv{@inheritDoc}
     * 
     * @throws NullPointerException if {@code toKey} is nullvand this map uses natural ordering, or
     * its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlyNavigableMap<K,V> headMap(K toKey, boolean inclusive)
    {
        return InterfaceBuilder.toReadOnlyNavigableMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._headMap
                    (toKey, inclusive, friendClassBadge)
                : this.treeMap.headMap(toKey, inclusive)
        );
    }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if {@code fromKey} is null and this map uses natural ordering,
     * or its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlyNavigableMap<K,V> tailMap(K fromKey, boolean inclusive)
    {
        return InterfaceBuilder.toReadOnlyNavigableMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._tailMap
                    (fromKey, inclusive, friendClassBadge)
                : this.treeMap.tailMap(fromKey, inclusive)
        );
    }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if {@code fromKey} or {@code toKey} is null and this map uses
     * natural ordering, or its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlySortedMap<K,V> subMap(K fromKey, K toKey)
    {
        return InterfaceBuilder.toReadOnlySortedMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._subMap
                    (fromKey, toKey, friendClassBadge)
                : this.treeMap.subMap(fromKey, toKey)
        );
    }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if {@code toKey} is null and this map uses natural ordering, or
     * its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlySortedMap<K,V> headMap(K toKey)
    {
        return InterfaceBuilder.toReadOnlySortedMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._headMap(toKey, friendClassBadge)
                : this.treeMap.headMap(toKey)
        );
    }

    /**
     * @throws ClassCastException {@inheritDoc}
     * 
     * @throws NullPointerException if {@code fromKey} is null and this map uses natural ordering,
     * or its comparator does not permit null keys
     * 
     * @throws IllegalArgumentException {@inheritDoc}
     */
    public ReadOnlySortedMap<K,V> tailMap(K fromKey)
    {
        return InterfaceBuilder.toReadOnlySortedMap(
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._tailMap(fromKey, friendClassBadge)
                : this.treeMap.tailMap(fromKey)
        );
    }

    @Override
    public void forEach(BiConsumer<? super K, ? super V> action)
    { this.treeMap.forEach(action); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Misc Stuff that is defined in a super-class - for java.util, but not for Java.ReadOnly
    // ********************************************************************************************
    // ********************************************************************************************


    public boolean isEmpty()
    { return this.treeMap.isEmpty(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a {@code String} representation of this map. The {@code String} representation
     * consists of a list of key-value mappings in the order returned by the map's entrySet view's
     * iterator, enclosed in braces ({@code "{}"}). Adjacent mappings are separated by the
     * characters {@code ", "} (comma and space).  Each key-value mapping is rendered as the key
     * followed by an equals sign ({@code "="}) followed by the associated value.  Keys and values
     * are converted to {@code String's} as by {@code String.valueOf(Object)}.
     * 
     * @return a {@code String} representation of this {@code TreeMap} 
     */
    public String toString()
    {
        return ROHelpers.toString(
            this.treeMap, // if the map contains itself, it is needed for printing purposes
            fromBuilderOrTreeMap
                ? ((ROTreeMapBuilder<K, V>) this.treeMap)._entrySet(friendClassBadge)
                : this.treeMap.entrySet()
        );
    }

    /**
     * Compares the specified Object with this Map for equality, as per the definition in the 
     * class {@code java.util.TreeMap}.
     *
     * @param  o object to be compared for equality with this {@code ReadOnlyTreeMap}.
     * @return {@code TRUE} if the specified Object is equal to this map
     */
    public boolean equals(Object o)
    { return ROHelpers.roMapEq(this, o); }

    /**
     * Returns the hash code value for this Map as per the definition in the class
     * {@code java.util.TreeMap}.
     */
    public int hashCode() 
    { return this.treeMap.hashCode(); }

}