Class ReadOnlyTreeMap<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Implemented Interfaces:
    java.io.Serializable, ReadOnlyMap<K,​V>, ReadOnlyNavigableMap<K,​V>, ReadOnlySequencedMap<K,​V>, ReadOnlySortedMap<K,​V>
    public class ReadOnlyTreeMap<K,​V>
extends java.lang.Object
implements ReadOnlyNavigableMap<K,​V>, java.io.Serializable
    This class was originally copied from GitHub's Open-JDK Account. It has been heavily modified as all method bodies have been removed; although few changes were applied to the file's Javadoc Commenting. Method and parameter names & types have not been modified whatsoever - although several methods have been eliminated.

    This file contains quite a bit of Wrapper-Code which has been placed around the code from the original Open JDK-21 Source-File of the same (or, rather, highly similar) Class-Name. The original JDK Source-File may be viewed on the JDK-21 GitHub public (and, coincidentally, Read-Only) Source-Release archive for Java Package java.util.*

    The Original '.java' Source-File's Header-Copyright Information is included here: File Copyright. Within that Copyright Notice, it is suggested that a copy of the GNU Public License V2 also be included alongside.
    Immutable Wrapper for java.util.TreeMap, found in the "Java Collections Framework".

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'TreeMap' contains - except those which would directly or indirectly modify / mutate the internal data-structure.

    In order to guarantee that the contents and values of this TreeMap remain constant and unchanged, this class retains an internal TreeMap, and assigns it the Java modifier 'private' to prevent any outside, unwanted modification. This class' own methods are all trivial, single-line wrappers that invoke the original java.util methods, but leave out any & all wrappers for methods that have the ability to modify, update, remove or insert values into the internal and private TreeMap.

    Finally, this class offers a Read Only Guarantee, which is enforced by preventing any instantiation of this class from occuring that would allow outside references of its internal, private TreeMap field

    Immutable interface Inheritance-Tree:
    This class implements a variant of the JDK's java.util.* Interface-Stack, all of which have been slightly modified (and renamed to add the prefix 'ReadOnly' to their names). This decision was necessary because many of the support functions inside Java Collection Framework classes have utility / helper methods that retrieve & generate Sub-Maps and Sub-Sets that are linked to the original Collection's, Set's and Map's from whence they were produced.

    These Sub-Map / Sub-Set retrieval methods all sing the same refrain - changes to the returned Map / Set will be reflected into 'this' instance, and vice-versa.

    These Sub-Map's and Sub-Set's would easily (even though 'accidentally') provide a dangerous back-door means for modifying and updating a Collection that is claiming to be Read-Only & Immutable.

    As a result, the decision was made to also port all of the java.util.* interfaces, such as Set, Map, List & Collection, into the Read-Only Collections Framework by renaming them to ReadOnlySet, ReadOnlyMap, & ReadOnlyCollection - and of course to remove / eliminate all Mutator-Methods from those interfaces. This extra step further guarantees the provision that this Data-Class is, truly, Read-Only and un-modifiable.

    Self-Referential ReadOnlyTreeMap's
    Though likely uncommon in most typical software projects, it is possible for a TreeMap to actually contain a reference to itself. However, in the translation from a standard TreeMap to a ReadOnlyTreeMap, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyTreeMap which is being constructed.

    Java's Generic Type-System, generally, makes such references nearly (but not completely) impossible. Unless you have assigned java.lang.Object to the Data-Class' Generic-Type, there is likely no common Ancestor-Type that would inherit both a ReadOnlyTreeMap, and the other objects in your data-set.

    As a result, if you happen to pass an instance of data that contains references or pointers to itself, those pointers will not be updated to reference the Read-Only variant of your Data-Structure when that Data-Structure is created. The ReadOnlyTreeMap that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!
    See Also:
    Serialized Form


    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

    • Constructor Detail

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​(java.util.Map<K,​V> map)
        Copies the contents of parameter 'map', and saves saves it, thereby guaranteeing 'this' instance is Read-Only and fully-shielded from outside modification.
        Parameters:
        map - The Map to be copied into 'this' instance internal and private 'treeMap' field.
        Code:
        Exact Constructor Body:
         this.fromBuilderOrTreeMap = false;

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

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​
            (Tuple2<K,​V> refHolder,
             java.util.Map<X,​Y> map,
             java.util.function.Consumer<java.util.Map.Entry<X,​Y>> mapTranslator,
             java.util.function.Predicate<java.util.Map.Entry<X,​Y>> filter,
             java.util.Comparator<? super K> comparator)
        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 - this constructor can convert any Java Map into a ReadOnlyTreeMap, using a simple 'mapTranslator'.
        Type Parameters:
        X - The Key-Type of the User-Provided Map.
        Y - The Value-Type of the User-Provided Map.
        Parameters:
        refHolder - This must a non-null instance of Tuple2. The provided Consumer is just that, a 'Consumer' rather than a '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 ReadOnlyTreeMap.
        map - Any Java Map.
        mapTranslator - A function for mapping the iterated elements of Map-Types 'X' and 'Y', into the actual TreeMap's Key-Type 'K', and Value-Type 'V'. The results of this translation must be placed into the fields inside 'refHolder'.

        If this parameter is passed null, this method will throw a NullPointerException.
        filter - An optional filter that can be used to prevent & prohibit any chosen elements from input 'map' from being inserted into 'this' ReadOnlyTreeMap.

        This parameter may be passed null, and if it is, it will be silently ignored, and all entries present inside 'map' will be processed and inserted into 'this'
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either parameter 'i' or parameter 'mapTranslator' is passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​
            (java.lang.Iterable<? extends K> keys,
             java.util.function.Function<? super K,​? extends V> valueMapper,
             java.util.function.Predicate<? super K> filter,
             java.util.Comparator<? super K> comparator)
        Constructs an instance of ReadOnlyTreeMap that contains the keys present in parameter 'keys', and values generated by 'valueMapper' - using each of the 'keys' as input.

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyTreeMap's internal TreeMap.
        Parameters:
        keys - Any Java Iterable instance.
        valueMapper - A user provided function to compute a map value, based on a map key.
        filter - This parameter may be used to filter some elements returned by the input Iterable instance.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the Iterable parameter are processed and inserted.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either 'keys' or 'valueMapper' are passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​(Tuple2<K,​V> refHolder,
                       java.lang.Runnable computeNextEntry,
                       java.util.Comparator<? super K> comparator)
        Constructs an instance of ReadOnlyTreeMap that has been populated by the Key-Value Pairs left in 'refHolder' by each invocation of the Runnable parameter 'computeNextEntry'. Key-Value Pairs are inserted until an invocation of the Runnable leaves null in refHolder.a and refHolder.b

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyTreeMap's internal TreeMap.
        Parameters:
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyTreeMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyTreeMap using this 'refHolder'.
        computeNextEntry - This Runnable instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyTreeMap instance. The Lambda-Expression or Method provided to this Runnable must place each Key-Value Pair into the 'refHolder' instance.

        After each insertion that is performed, the logic will check if the Key and Value of Tuple2 instance have been passed null. When both the Key and the Value are null, this Constructor will cease inserting data into this instance internal TreeMap, and exit.

        NOTE: It is acceptabe for this Runnable to return multiple values for a single Key. If redundant Keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored TreeMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​
            (java.lang.Iterable<X> source,
             Tuple2<K,​V> refHolder,
             java.util.function.Consumer<? super X> computeNextEntry,
             java.util.function.Predicate<? super X> filter,
             java.util.Comparator<? super K> comparator)
        Populates an instance of ReadOnlyTreeMap by iterating the input 'source' iterable, and passing each value returned by that Iterator to the 'computeNextEntry' Java Consumer.

        It is the programmer's responsibility to properly place each Key-Value Pair that is intending to be inserted into the final Map instance into the 'refHolder' instance. After each invocation of 'computeNextEntry', this constructor's logic will retrieve the values within 'refHolder.a' and 'refHolder.b' and insert them into this instance internal TreeMap.

        Constructor Body:
        It is likely of the highest benefit to simply look at the imported Constructor-Body Code-Snippet below to understand the exact mechanics of how this constructor incorporates data into this ReadOnlyTreeMap's internal TreeMap.
        Type Parameters:
        X - The type of the elements inside 'source'
        Parameters:
        source - Any Java Iterable instance.
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyTreeMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyTreeMap using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyTreeMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the input 'source' parameter Iterable-instance (which is iterated in this constructor's body).

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored TreeMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        filter - This parameter may be used to filter some elements returned by the input Iterable instance.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the Iterable parameter are processed and inserted.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either 'refHolder', 'computeNextEntry' or 'source' are passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​
            (Tuple2<K,​V> refHolder,
             java.util.function.Consumer<? super X> computeNextEntry,
             java.util.function.Predicate<? super X> filter,
             java.util.Comparator<? super K> comparator,
             X... elements)
        Retrieves elements from the VarArgs Generic-Array parameter 'elements', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyTreeMap.
        Type Parameters:
        X - The type of array parameter 'elements'
        Parameters:
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyTreeMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyTreeMap using this 'refHolder'.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyTreeMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the user-provided input-array.

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored TreeMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        filter - This parameter may be used to filter elements from the array-instance, preventing them from being inserted into the ReadOnlyTreeMap.

        This parameter may be passed null, and if it is, it will be silently ignored. When it is ignored, all elements from the array parameter are processed and inserted.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - Any Generic VarArgs-Array
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeMap​(java.util.function.Predicate<?> filter,
                       java.util.function.Consumer<?> computeNextEntry,
                       Tuple2<K,​V> refHolder,
                       java.util.Comparator<? super K> comparator,
                       java.lang.Object primitiveArray)
        Retrieves elements from the Java Primitive-Array parameter 'primitiveArray', and subsequently invokes the 'computeNextEntry' processor to populate this ReadOnlyTreeMap.
        Parameters:
        filter - The Java Predicate passed to this parameter must have a test(...) method that can handle input-references of the Java Boxed-Type that corresponds to the Java-Primitive Type used in parameter 'primitiveArray'.

        In English this means, If you have pased an int[]-Array to 'primitiveArray', and would like to filter some of the elements out of your ReadOnlyTreeMap, then you should pass a Predicate<java.lang.Integer> to this parameter.

        If you have passed a char[]-Array, then this parameter should be a Predicate<java.lang.Character> - and so on and so forth...

        NOTE: This is, indeed, a Run-Time rather than a Compile-Time Type-Solution. If you would like to know what that means (in plain English), it is as follows: There isn't a way to request that the Java-Compiler ensure, and print error-messages on error, that you have passed a Predicate<Integer> for an int[]-Array and a Predicate<Float> for a float[]-Array.

        If an erroneous Predicate is passed to parameter 'filter', then, during Run-Time, a ClassCastException will throw - rather than having a Compile-Time Error generated.
        computeNextEntry - This Consumer instance will be called to compute the Key-Value Pairs that are to be inserted into this ReadOnlyTreeMap instance. The Lambda-Expression or Method provided to this Consumer must place each Key-Value Pair into the 'refHolder' instance.

        Passed as input to this Consumer will simply be the elements from the user-provided input-array.

        NOTE: It is acceptabe for this Consumer to return multiple values for a single Key. If redundant keys are placed into the 'refHolder', the old value assigned to the key will be over-written by the latest value. If both a key and a value placed into 'refHolder' are duplicates, both will be reinserted a second time, which doesn't have any effect on the internally stored TreeMap.

        Again, for a detailed understanding of how to use this parameter, it is best just to look at the imported Constructor-Body below!
        refHolder - Any instance of Tuple2 may be passed to this parameter. This reference may not be null, or a NullPointerException will throw immediately.

        This parameter must be used to populate this ReadOnlyTreeMap instance.

        The 'computeNextEntry' instance provided to this method, when invoked, should place each Key-Value Pair that it computes into the two fields of this 'refHolder'. After invoking the 'computeNextEntry' consumer, the contents of this Tuple2 are inserted into this ReadOnlyMap instance.

        Please review the Source-Code in the window below. It, hopefully, elucidates how this method retrieves the data to be placed into this ReadOnlyTreeMap using this 'refHolder'.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        primitiveArray - Any Java Primitive-Array
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - if either 'refHolder' or 'computeNextEntry' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(refHolder, ROHelpers.NULL_MSG + "'refHolder'");
 Objects.requireNonNull(computeNextEntry, ROHelpers.NULL_MSG + "'computeNextEntry'");

 this.fromBuilderOrTreeMap = false;

 TreeMap<K, V> treeMap = ROHelperPrimitiveArrays.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;

    • Method Detail

      • emptyROTM

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <X,​Y> ReadOnlyTreeMap<X,​Y> emptyROTM()
        Returns an empty, singleton, instance of ReadOnlyTreeMap.
        Type Parameters:
        X - Returned ReadOnlyMap's Key-Type.
        Y - Returned ReadOnlyMap's Value-Type.
        Returns:
        An empty map. Since this map is both empty & read-only, a raw-type singleton will suffice for all operations offered by this clas.

        NOTE: The instance that is returned is a static, final constant which is constructed during the loading of this class by the Class-Loader. It is fully Thread-Safe, unless it is going to be used as an Object-Monitor to help lock a Synchronized Code-Block!
        Code:
        Exact Method Body:
         return (ReadOnlyTreeMap<X, Y>) EMPTY_READONLY_TREE_MAP;

      • cloneToTreeMapOLD

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.TreeMap<K,​V> cloneToTreeMapOLD()
        Clone's 'this' instance internal TreeMap<K, V> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyTreeMap. The instance that's returned by this method is a clone, and this decision preserves the immutable (Read-Only) protection offered by this class.

        Standard JDK TreeMap
        The returned object is a Standard JDK TreeMap data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal TreeMap, it is not actually 'linked' to the internal TreeMap

        This does mean that changes to the returned TreeMap instance will not be reflected to the 'this' ReadOnlyTreeMap. They are, in fact, two independent and unlinked copies of the internal data.
        Returns:
        An independent, mutable copy of 'this' instance internal TreeMap<K, V> data-structure.
        Code:
        Exact Method Body:
         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;

      • size

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int size()
        Returns the number of key-value mappings in this map.
        Specified by:
        size in interface ReadOnlyMap<K,​V>
        Returns:
        the number of key-value mappings in this map
        Code:
        Exact Method Body:
         return this.treeMap.size();

      • containsKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsKey​(java.lang.Object key)
        Returns TRUE if this map contains a mapping for the specified key.
        Specified by:
        containsKey in interface ReadOnlyMap<K,​V>
        Parameters:
        key - key whose presence in this map is to be tested
        Returns:
        TRUE if this map contains a mapping for the specified key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.containsKey(key);

      • containsValue

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsValue​(java.lang.Object value)
        Returns TRUE if this map maps one or more keys to the specified value. More formally, returns TRUE if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)).
        Specified by:
        containsValue in interface ReadOnlyMap<K,​V>
        Parameters:
        value - value whose presence in this map is to be tested
        Returns:
        TRUE if a mapping to value exists; FALSE otherwise
        Code:
        Exact Method Body:
         return this.treeMap.containsValue(value);

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public V get​(java.lang.Object key)
        Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

        More formally, if this map contains a mapping from a key k to a value v such that key compares equal to k according to the map's ordering, then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

        A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
        Specified by:
        get in interface ReadOnlyMap<K,​V>
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified key is mapped, or null if this map contains no mapping for the key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.get(key);

      • comparator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Comparator<? super K> comparator()
        Description copied from interface: ReadOnlySortedMap
        Returns the comparator used to order the keys in this map, or null if this map uses the natural ordering of its keys.
        Specified by:
        comparator in interface ReadOnlySortedMap<K,​V>
        Returns:
        the comparator used to order the keys in this map, or null if this map uses the natural ordering of its keys
        Code:
        Exact Method Body:
         return this.treeMap.comparator();

      • firstKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K firstKey()
        Description copied from interface: ReadOnlySortedMap
        Returns the first (lowest) key currently in this map.
        Specified by:
        firstKey in interface ReadOnlySortedMap<K,​V>
        Returns:
        the first (lowest) key currently in this map
        Throws:
        java.util.NoSuchElementException
        Code:
        Exact Method Body:
         return this.treeMap.firstKey();

      • lastKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K lastKey()
        Description copied from interface: ReadOnlySortedMap
        Returns the last (highest) key currently in this map.
        Specified by:
        lastKey in interface ReadOnlySortedMap<K,​V>
        Returns:
        the last (highest) key currently in this map
        Throws:
        java.util.NoSuchElementException
        Code:
        Exact Method Body:
         return this.treeMap.lastKey();

      • lowerEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyMap.Entry<K,​V> lowerEntry​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such key.
        Specified by:
        lowerEntry in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the greatest key less than key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return new EntryImpl<>(this.treeMap.lowerEntry(key));

      • lowerKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K lowerKey​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns the greatest key strictly less than the given key, or null if there is no such key.
        Specified by:
        lowerKey in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the greatest key less than key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.lowerKey(key);

      • floorEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyMap.Entry<K,​V> floorEntry​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such key.
        Specified by:
        floorEntry in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the greatest key less than or equal to key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return new EntryImpl<>(this.treeMap.floorEntry(key));

      • floorKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K floorKey​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns the greatest key less than or equal to the given key, or null if there is no such key.
        Specified by:
        floorKey in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the greatest key less than or equal to key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.floorKey(key);

      • ceilingEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyMap.Entry<K,​V> ceilingEntry​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such key.
        Specified by:
        ceilingEntry in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the least key greater than or equal to key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return new EntryImpl<>(this.treeMap.ceilingEntry(key));

      • ceilingKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K ceilingKey​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns the least key greater than or equal to the given key, or null if there is no such key.
        Specified by:
        ceilingKey in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the least key greater than or equal to key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.ceilingKey(key);

      • higherEntry

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyMap.Entry<K,​V> higherEntry​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such key.
        Specified by:
        higherEntry in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        an entry with the least key greater than key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return new EntryImpl<>(this.treeMap.higherEntry(key));

      • higherKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public K higherKey​(K key)
        Description copied from interface: ReadOnlyNavigableMap
        Returns the least key strictly greater than the given key, or null if there is no such key.
        Specified by:
        higherKey in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        key - the key
        Returns:
        the least key greater than key, or null if there is no such key
        Throws:
        java.lang.ClassCastException - if the specified key cannot be compared with the keys currently in the map
        java.lang.NullPointerException - if the specified key is null and this map uses natural ordering, or its comparator does not permit null keys
        Code:
        Exact Method Body:
         return this.treeMap.higherKey(key);

      • keySet

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySet<K> keySet()
        Returns a ReadOnlySet view of the keys contained in this map.
        Specified by:
        keySet in interface ReadOnlyMap<K,​V>
        Specified by:
        keySet in interface ReadOnlySortedMap<K,​V>
        Returns:
        a set view of the keys contained in this map, sorted in ascending order
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._keySet(friendClassBadge)
         : this.treeMap.keySet()
 );

      • values

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyCollection<V> values()
        Returns a ReadOnlyCollection view of the values contained in this map.
        Specified by:
        values in interface ReadOnlyMap<K,​V>
        Specified by:
        values in interface ReadOnlySortedMap<K,​V>
        Returns:
        a collection view of the values contained in this map, sorted in ascending key order
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyCollection<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._values(friendClassBadge)
         : this.treeMap.values()
 );

      • subMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableMap<K,​V> subMap​(K fromKey,
                                              boolean fromInclusive,
                                              K toKey,
                                              boolean toInclusive)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys range from fromKey to toKey. If fromKey and toKey are equal, the returned map is empty unless fromInclusive and toInclusive are both true.

        The returned map supports all optional map operations that this map supports.
        Specified by:
        subMap in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        fromKey - low endpoint of the keys in the returned map
        fromInclusive - TRUE if the low endpoint is to be included in the returned view
        toKey - high endpoint of the keys in the returned map
        toInclusive - TRUE if the high endpoint is to be included in the returned view
        Returns:
        a view of the portion of this map whose keys range from fromKey to toKey
        Throws:
        java.lang.ClassCastException - if fromKey and 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 fromKey or toKey cannot be compared to keys currently in the map.
        java.lang.NullPointerException - if fromKey or toKey is null and this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if fromKey is greater than toKey; or if this map itself has a restricted range, and fromKey or toKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyNavigableMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._subMap
             (fromKey, fromInclusive, toKey, toInclusive, friendClassBadge)
         : this.treeMap.subMap(fromKey, fromInclusive, toKey, toInclusive)
 );

      • headMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableMap<K,​V> headMap​(K toKey,
                                               boolean inclusive)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey. The returned map supports all optional map operations that this map supports.
        Specified by:
        headMap in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        toKey - high endpoint of the keys in the returned map
        inclusive - TRUE if the high endpoint is to be included in the returned view
        Returns:
        a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey
        Throws:
        java.lang.NullPointerException - if toKey is nullvand this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if this map itself has a restricted range, and toKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyNavigableMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._headMap
             (toKey, inclusive, friendClassBadge)
         : this.treeMap.headMap(toKey, inclusive)
 );

      • tailMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableMap<K,​V> tailMap​(K fromKey,
                                               boolean inclusive)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey. The returned map supports all optional map operations that this map supports.
        Specified by:
        tailMap in interface ReadOnlyNavigableMap<K,​V>
        Parameters:
        fromKey - low endpoint of the keys in the returned map
        inclusive - TRUE if the low endpoint is to be included in the returned view
        Returns:
        a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey
        Throws:
        java.lang.ClassCastException - if fromKey is not compatible with this map's comparator (or, if the map has no comparator, if fromKey does not implement Comparable). Implementations may, but are not required to, throw this exception if fromKey cannot be compared to keys currently in the map.
        java.lang.NullPointerException - if fromKey is null and this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if this map itself has a restricted range, and fromKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyNavigableMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._tailMap
             (fromKey, inclusive, friendClassBadge)
         : this.treeMap.tailMap(fromKey, inclusive)
 );

      • subMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedMap<K,​V> subMap​(K fromKey,
                                           K toKey)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive. (If fromKey and 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.

        The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.

        Equivalent to subMap(fromKey, true, toKey, false).
        Specified by:
        subMap in interface ReadOnlyNavigableMap<K,​V>
        Specified by:
        subMap in interface ReadOnlySortedMap<K,​V>
        Parameters:
        fromKey - low endpoint (inclusive) of the keys in the returned map
        toKey - high endpoint (exclusive) of the keys in the returned map
        Returns:
        a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive
        Throws:
        java.lang.ClassCastException - if fromKey and 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 fromKey or toKey cannot be compared to keys currently in the map.
        java.lang.NullPointerException - if fromKey or toKey is null and this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if fromKey is greater than toKey; or if this map itself has a restricted range, and fromKey or toKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySortedMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._subMap
             (fromKey, toKey, friendClassBadge)
         : this.treeMap.subMap(fromKey, toKey)
 );

      • headMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedMap<K,​V> headMap​(K toKey)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys are strictly less than 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.

        The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.

        Equivalent to headMap(toKey, false).
        Specified by:
        headMap in interface ReadOnlyNavigableMap<K,​V>
        Specified by:
        headMap in interface ReadOnlySortedMap<K,​V>
        Parameters:
        toKey - high endpoint (exclusive) of the keys in the returned map
        Returns:
        a view of the portion of this map whose keys are strictly less than toKey
        Throws:
        java.lang.ClassCastException - if toKey is not compatible with this map's comparator (or, if the map has no comparator, if toKey does not implement Comparable). Implementations may, but are not required to, throw this exception if toKey cannot be compared to keys currently in the map.
        java.lang.NullPointerException - if toKey is null and this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if this map itself has a restricted range, and toKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySortedMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._headMap(toKey, friendClassBadge)
         : this.treeMap.headMap(toKey)
 );

      • tailMap

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedMap<K,​V> tailMap​(K fromKey)
        Description copied from interface: ReadOnlyNavigableMap
        Returns a view of the portion of this map whose keys are greater than or equal to 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.

        The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.

        Equivalent to tailMap(fromKey, true).
        Specified by:
        tailMap in interface ReadOnlyNavigableMap<K,​V>
        Specified by:
        tailMap in interface ReadOnlySortedMap<K,​V>
        Parameters:
        fromKey - low endpoint (inclusive) of the keys in the returned map
        Returns:
        a view of the portion of this map whose keys are greater than or equal to fromKey
        Throws:
        java.lang.ClassCastException - if fromKey is not compatible with this map's comparator (or, if the map has no comparator, if fromKey does not implement Comparable). Implementations may, but are not required to, throw this exception if fromKey cannot be compared to keys currently in the map.
        java.lang.NullPointerException - if fromKey is null and this map uses natural ordering, or its comparator does not permit null keys
        java.lang.IllegalArgumentException - if this map itself has a restricted range, and fromKey lies outside the bounds of the range
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySortedMap<>(
     fromBuilderOrTreeMap
         ? ((ROTreeMapBuilder<K, V>) this.treeMap)._tailMap(fromKey, friendClassBadge)
         : this.treeMap.tailMap(fromKey)
 );

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​
            (java.util.function.BiConsumer<? super K,​? super V> action)
        Description copied from interface: ReadOnlyMap
        Performs the given action for each entry in this map until all entries have been processed or the action throws an exception. Unless otherwise specified by the implementing class, actions are performed in the order of entry set iteration (if an iteration order is specified.) Exceptions thrown by the action are relayed to the caller.

        The default implementation is equivalent to, for this map: 

         for (ReadOnlyMap.Entry<K, V> entry : map.entrySet())
     action.accept(entry.getKey(), entry.getValue());


        The default implementation makes no guarantees about synchronization or atomicity properties of this method. Any implementation providing atomicity guarantees must override this method and document its concurrency properties.
        Specified by:
        forEach in interface ReadOnlyMap<K,​V>
        Parameters:
        action - The action to be performed for each entry
        Code:
        Exact Method Body:
         this.treeMap.forEach(action);

      • isEmpty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean isEmpty()
        Description copied from interface: ReadOnlyMap
        Returns TRUE if this map contains no key-value mappings.
        Specified by:
        isEmpty in interface ReadOnlyMap<K,​V>
        Returns:
        TRUE if this map contains no key-value mappings
        Code:
        Exact Method Body:
         return this.treeMap.isEmpty();

      • cloneToTreeMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.TreeMap<K,​V> cloneToTreeMap()
        Clone's 'this' instance internal TreeMap<K, V> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyTreeMap. The instance that's returned by this method is a clone, and this decision preserves the immutable (Read-Only) protection offered by this class.

        Standard JDK TreeMap
        The returned object is a Standard JDK TreeMap data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal TreeMap, it is not actually 'linked' to the internal TreeMap

        This does mean that changes to the returned TreeMap instance will not be reflected to the 'this' ReadOnlyTreeMap. They are, in fact, two independent and unlinked copies of the internal data.
        Returns:
        An independent, mutable copy of 'this' instance' internal TreeMap<K, V> data-structure.
        Code:
        Exact Method Body:
         return fromBuilderOrTreeMap
     ? new TreeMap<K, V>(this.treeMap)
     : (TreeMap<K, V>) this.treeMap.clone();

      • cloneToMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map<K,​V> cloneToMap()
        Converts this ReadOnlyTreeMap to a java.util.TreeMap
        Same: Identical to the method cloneToTreeMap().
        Returns: Has Return-Type Map<K, V>, instead.
        Implements: Parent-Class ReadOnlyMap.cloneToMap()
        Specified by:
        cloneToMap in interface ReadOnlyMap<K,​V>
        Returns:
        • For the sub-class ReadOnlyHashMap, this will return a cloned instance of the internal java.util.HashMap.

        • For the sub-class ReadOnlyTreeMap, this will return a cloned instance of the internal java.util.TreeMap.

        • For the sub-class ReadOnlyHashtable, this will return a cloned instance of the internal java.util.Hashtable.

        • For the sub-class ReadOnlyProperties, this will return a cloned instance of the internal java.util.Properties.
        Code:
        Exact Method Body:
         return cloneToTreeMap();

      • wrapToImmutableMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Map<K,​V> wrapToImmutableMap()
        Description copied from interface: ReadOnlyMap
        Invokes java.util.Collections.unmodifiableMap on the internal Map

        Standard JDK Map:
        There may be situations where the Type ReadOnlyMap is simply not usable with an API that can't be adapted to accept Type's from the Java-HTML ReadOnly Package. If such a case arises, this method can be used to generate an immutable instance of a JDK-Standard java.util Type, which does not inherit from Torello.Java.ReadOnly

        Class java.util.Collections offers a method that wraps a type into an Unmodifiable-Wrapper that implements the standard java.util.Map, but throws an exception if any attempts are made to invoke Mutator-Methods.

        Unmodifiable-Collections throw Exceptions instead:
        The returned java.util.Map instance will hopefully provide an acceptable substitute when ReadOnly Type's cannot match an API's requirements. Java's Immutable-Wrappers work on a different principle - these classes retain any / all Mutator-Methods amongst their Type-Members, but instead throw an UnsupportedOperationException if any of those methods are invoked!

        Also, if a Java Collections Framework Unmodifiable-Class has any Member-Methods that return a "View" into the underlying Data-Structure, the Sub-Lists and Sub-Maps returned by those methods are also, subsequently, wrapped in an Unmodifiable-Wrapper. These returned instances will also throw an UnsupportedOperationException if any of those methods are invoked!

        This does provide a shield or layer of protection against modification to guarantee the "Immutability-Contract" offered by these classes, all-the-while returning to native Java API Collection Types, rather than Torello.Java.ReadOnly Types, which may not always be compatible with a given API or Interface requirement!

        Remember, many of the Data-Classes inside java.util have methods whose documentation state very clearly that "any changes made the this [View] will be pushed back into the original type."
        Specified by:
        wrapToImmutableMap in interface ReadOnlyMap<K,​V>
        Returns:
        A Set which adheres to the JDK interface java.util.Set, but throws an UnsupportedOperationException if a user attempts to invoke a Mutator-Method on the returned instance.
        Code:
        Exact Method Body:
         return Collections.unmodifiableMap(this.treeMap);

      • toString

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of this map. The 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 ("{}"). Adjacent mappings are separated by the characters ", " (comma and space). Each key-value mapping is rendered as the key followed by an equals sign ("=") followed by the associated value. Keys and values are converted to String's as by String.valueOf(Object).
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this TreeMap
        Code:
        Exact Method Body:
         return ROHelperEntrySet.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()
 );

      • equals

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this Map for equality, as per the definition in the class java.util.TreeMap.
        Specified by:
        equals in interface ReadOnlyMap<K,​V>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this ReadOnlyTreeMap.
        Returns:
        TRUE if the specified Object is equal to this map
        Code:
        Exact Method Body:
         return ROHelperEquals.roMapEq(this, o);