Interface ReadOnlyMap<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Known Subinterfaces:
    ReadOnlyNavigableMap<K,​V>, ReadOnlySequencedMap<K,​V>, ReadOnlySortedMap<K,​V>
    All Known Implementing Classes:
    ReadOnlyHashMap, ReadOnlyHashtable, ReadOnlyProperties, ReadOnlyTreeMap
    public interface ReadOnlyMap<K,​V>
    This interface was originally copied from GitHub's Open-JDK Account. Though the original file has been modified, few changes have been applied to the Javadoc Commenting. Due to fact that that is a Java interface file, there were few method bodies with Source-Code to begin with - meaning this is largely a copy of Method-Signatures and Java-Doc Comments.

    Method and parameter names & types have not been modified whatsoever; but several methods had to be eliminated for not being Read-Only. This Source-File was copied from the original Open JDK-21 file of the same (or, rather, highly similar) Interface-Name. The original 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 variant of Java Collections Framework interface java.util.Map<K, V>. This interface contains all of the methods that the standard Java interface ReadOnlyMap contains - except those which would directly or indirectly modify / mutate the internal data-structure.


    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface
      static interface  ReadOnlyMap.Entry<K,​V>

    • Method Summary

       
      Retrieve a Map Value
      Modifier and Type Method
      V get​(Object key)
       
      Retrieve a Set of all Map Keys
      Modifier and Type Method
      ReadOnlySet<K> keySet()
       
      Retrieve a Collection of all Map Values
      Modifier and Type Method
      ReadOnlyCollection<V> values()
       
      Check this Map's Contents
      Modifier and Type Method
      boolean containsKey​(Object key)
      boolean containsValue​(Object value)
      boolean isEmpty()
      int size()
       
      Retrieve a Set of Key-Value Pairs
      Modifier and Type Method
      ReadOnlySet<ReadOnlyMap.Entry<K,
           ​V>>      		 entrySet()
       
      Convert 'this' to a Standard 'java.util' Collections-Framework Type
      Modifier and Type Method
      Map<K,​V> cloneToMap()
      Map<K,​V> wrapToImmutableMap()
       
      Static Methods: Builder's
      Modifier and Type Method
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of()
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)
       
      Static Methods: Builders that utilize inner-class 'Entry'
      Modifier and Type Method
      static <K,
           ​V>
      ReadOnlyMap.Entry<K,
           ​V>      		 entry​(K k, V v)
      static <K,​V>
      ReadOnlyMap<K,​V>      		 ofEntries​(ReadOnlyMap.Entry<? extends K,​? extends V>... entries)
       
      Default Methods (Interface Methods with a Concrete, Default Implementation)
      Modifier and Type Method
      default void copyIntoMap​(Map<? super K,​? super V> map)
      default void forEach​(BiConsumer<? super K,​? super V> action)
      default V getOrDefault​(Object key, V defaultValue)
       
      Default Methods: VarArgs Input, Keys - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsKeyAND​(Object... elements)
      default boolean containsKeyNAND​(Object... elements)
      default boolean containsKeyOR​(Object... elements)
      default boolean containsKeyXOR​(Object... elements)
       
      Default Methods: Iterable Input, Keys - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsKeyAND​(Iterable<?> i)
      default boolean containsKeyNAND​(Iterable<?> i)
      default boolean containsKeyOR​(Iterable<?> i)
      default boolean containsKeyXOR​(Iterable<?> i)
       
      Default Methods: VarArgs Input, Values - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsValueAND​(Object... elements)
      default boolean containsValueNAND​(Object... elements)
      default boolean containsValueOR​(Object... elements)
      default boolean containsValueXOR​(Object... elements)
       
      Default Methods: Iterable Input, Values - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsValueAND​(Iterable<?> i)
      default boolean containsValueNAND​(Iterable<?> i)
      default boolean containsValueOR​(Iterable<?> i)
      default boolean containsValueXOR​(Iterable<?> i)
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      int hashCode()

    • Method Detail

      • size

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int size()
        Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
        Returns:
        the number of key-value mappings in this map

      • isEmpty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean isEmpty()
        Returns TRUE if this map contains no key-value mappings.
        Returns:
        TRUE if this map contains no key-value mappings

      • containsKey

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean containsKey​(java.lang.Object key)
        Returns TRUE if this map contains a mapping for the specified key. More formally, returns TRUE if and only if this map contains a mapping for a key k such that Objects.equals(key, k). (There can be at most one such mapping.)
        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 key is of an inappropriate type for this map (optional-restrictions)
        java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional-restrictions)

      • containsValue

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 Objects.equals(value, v). This operation will probably require time linear in the map size for most implementations of the Map interface.
        Parameters:
        value - value whose presence in this map is to be tested
        Returns:
        TRUE if this map maps one or more keys to the specified value
        Throws:
        java.lang.ClassCastException - if the value is of an inappropriate type for this map (optional-restrictions)
        java.lang.NullPointerException - if the specified value is null and this map does not permit null values (optional-restrictions)

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 Objects.equals(key, k), then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

        If this map permits null values, then 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.
        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 key is of an inappropriate type for this map (optional-restrictions)
        java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional-restrictions)

      • keySet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        ReadOnlySet<K> keySet()
        Returns a ReadOnlySet view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.
        Returns:
        a set view of the keys contained in this map

      • cloneToMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.Map<K,​V> cloneToMap()
        Clones the internal java.util.Map representation, and returns it. This is the Top-Level Interface-Variant of this method. It returns the Interface-Implementation java.util.Map.

        Alternate Variant:
        The four classes which implement the interface ReadOnlyMap (which are ReadOnlyHashMap, ReadOnlyTreeMap, ReadOnlyHashtable and ReadOnlyProperties), for convenience, also implement an identical "Wrap To" Method which returns the exact type of the internal Map representation (which are java.util.HashMap, java.util.TreeMap, java.util.Hashtable and java.util.Properties) - rather than the Interface-Type java.util.Map.
        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.

      • wrapToImmutableMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.Map<K,​V> wrapToImmutableMap()
        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."
        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.

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean equals​(java.lang.Object o)
        Compares the specified object with this map for equality. Returns TRUE if the given object is also a map and the two maps represent the same mappings. More formally, two maps m1 and m2 represent the same mappings if m1.entrySet().equals(m2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this map
        Returns:
        TRUE if the specified object is equal to this map

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int hashCode()
        Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view. This ensures that m1.equals(m2) implies that m1.hashCode()==m2.hashCode() for any two maps m1 and m2, as required by the general contract of Object.hashCode.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value for this map
        See Also:
        ReadOnlyMap.Entry.hashCode(), equals(Object)

      • getOrDefault

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default V getOrDefault​(java.lang.Object key,
                       V defaultValue)
        Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.
        Parameters:
        key - the key whose associated value is to be returned
        defaultValue - the default mapping of the key
        Returns:
        the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key
        Throws:
        java.lang.ClassCastException - if the key is of an inappropriate type for this map (optional-restrictions)
        java.lang.NullPointerException - if the specified key is null and this map does not permit null keys (optional-restrictions)
        Code:
        Exact Method Body:
         V v;
 return (((v = get(key)) != null) || containsKey(key))
     ? v
     : defaultValue;

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default void forEach​
            (java.util.function.BiConsumer<? super K,​? super V> action)
        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.
        Parameters:
        action - The action to be performed for each entry
        Throws:
        java.lang.NullPointerException - if the specified action is null
        Code:
        Exact Method Body:
         Objects.requireNonNull(action);

 for (ReadOnlyMap.Entry<K, V> entry : entrySet())
 {
     K k;
     V v;

     try
     {
         k = entry.getKey();
         v = entry.getValue();
     }

     catch (IllegalStateException ise)
     {
         // this usually means the entry is no longer in the map.
         // throw new ConcurrentModificationException(ise);

         throw new Torello.Java.UnreachableError();
     }

     action.accept(k, v);
 }

      • copyIntoMap

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default void copyIntoMap​(java.util.Map<? super K,​? super V> map)
        Copies the contents of 'this' ReadOnlyMap into the user-provided 'map'. Utilizes the java.util.Map method put(K key, V value).
        Parameters:
        map - Any instance of java.util.Map
        See Also:
        forEach(BiConsumer)
        Code:
        Exact Method Body:
         this.forEach((K k, V v) -> map.put(k, v));

      • containsKeyAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains a matching key for every one of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains every element in 'elements'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object elem : elements) if (! keys.contains(elem)) return false;
 return true;

      • containsKeyNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyNAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap does not contain any key that matches any of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains none of the elements in 'elements'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object elem : elements) if (keys.contains(elem)) return false;
 return true;

      • containsKeyOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains at least one key that matches at least one element in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains one or more of the elements in 'elements'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object elem : elements) if (keys.contains(elem)) return true;
 return false;

      • containsKeyXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyXOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains exactly one key that matches an element in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains precisely one element that is also in 'elements'
        Code:
        Exact Method Body:
         ReadOnlySet<K>  keys    = this.keySet();
 boolean         found   = false;

 for (Object elem : elements)

     if (keys.contains(elem))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • containsKeyAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains a matching key for every one of the elements in Iterable parameter 'i'.
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains every element in 'i'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object o: i) if (! keys.contains(o)) return false;
 return true;

      • containsKeyNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyNAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap does not contain any key that matches any of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains none of the elements in 'i'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object o: i) if (keys.contains(o)) return false;
 return true;

      • containsKeyOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains at least one key that matches at least one element in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains one or more of the elements in 'i'
        Code:
        Exact Method Body:
         ReadOnlySet<K> keys = this.keySet();
 for (Object o: i) if (keys.contains(o)) return true;
 return false;

      • containsKeyXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsKeyXOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains exactly one key that matches an element in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'keySet()' contains precisely one element that is also in 'i'
        Code:
        Exact Method Body:
         ReadOnlySet<K>  keys    = this.keySet();
 boolean         found   = false;

 for (Object o: i)

     if (keys.contains(o))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • containsValueAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains a matching value for every one of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains every element in 'elements'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object elem : elements) if (! values.contains(elem)) return false;
 return true;

      • containsValueNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueNAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap does not contain any value that matches any of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains none of the elements in 'elements'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object elem : elements) if (values.contains(elem)) return false;
 return true;

      • containsValueOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains at least one value that matches at least one element in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains one or more of the elements in 'elements'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object elem : elements) if (values.contains(elem)) return true;
 return false;

      • containsValueXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueXOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyMap contains exactly one value that matches an element in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains precisely one element that is also in 'elements'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V>   values  = this.values();
 boolean                 found   = false;

 for (Object elem : elements)

     if (values.contains(elem))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • containsValueAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains a matching value for every one of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains every element in 'i'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object o: i) if (! values.contains(o)) return false;
 return true;

      • containsValueNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueNAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap does not contain any value that matches any of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains none of the elements in 'i'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object o: i) if (values.contains(o)) return false;
 return true;

      • containsValueOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains at least one value that matches at least one element in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains one or more of the elements in 'i'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V> values = this.values();
 for (Object o: i) if (values.contains(o)) return true;
 return false;

      • containsValueXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsValueXOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyMap contains exactly one value that matches an element in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance' 'values()' contains precisely one element that is also in 'i'
        Code:
        Exact Method Body:
         ReadOnlyCollection<V>   values  = this.values();
 boolean                 found   = false;

 for (Object o: i)

     if (values.contains(o))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of()
        Returns an unmodifiable map containing zero mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Returns:
        an empty Map
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of());

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1)
        Returns an unmodifiable map containing a single mapping.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the mapping's key
        v1 - the mapping's value
        Returns:
        a ReadOnlyMap containing the specified mapping
        Throws:
        java.lang.NullPointerException - if the key or the value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of(k1, v1));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2)
        Returns an unmodifiable map containing two mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if the keys are duplicates
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of(k1, v1, k2, v2));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3)
        Returns an unmodifiable map containing three mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of(k1, v1, k2, v2, k3, v3));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4)
        Returns an unmodifiable map containing four mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of(k1, v1, k2, v2, k3, v3, k4, v4));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5)
        Returns an unmodifiable map containing five mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(Map.of(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5,
                                             K k6,
                                             V v6)
        Returns an unmodifiable map containing six mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        k6 - the sixth mapping's key
        v6 - the sixth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>
     (Map.of(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, k6, v6));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5,
                                             K k6,
                                             V v6,
                                             K k7,
                                             V v7)
        Returns an unmodifiable map containing seven mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        k6 - the sixth mapping's key
        v6 - the sixth mapping's value
        k7 - the seventh mapping's key
        v7 - the seventh mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>
     (Map.of(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, k6, v6, k7, v7));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5,
                                             K k6,
                                             V v6,
                                             K k7,
                                             V v7,
                                             K k8,
                                             V v8)
        Returns an unmodifiable map containing eight mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        k6 - the sixth mapping's key
        v6 - the sixth mapping's value
        k7 - the seventh mapping's key
        v7 - the seventh mapping's value
        k8 - the eighth mapping's key
        v8 - the eighth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>
     (Map.of(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, k6, v6, k7, v7, k8, v8));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5,
                                             K k6,
                                             V v6,
                                             K k7,
                                             V v7,
                                             K k8,
                                             V v8,
                                             K k9,
                                             V v9)
        Returns an unmodifiable map containing nine mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        k6 - the sixth mapping's key
        v6 - the sixth mapping's value
        k7 - the seventh mapping's key
        v7 - the seventh mapping's value
        k8 - the eighth mapping's key
        v8 - the eighth mapping's value
        k9 - the ninth mapping's key
        v9 - the ninth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>
     (Map.of(k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, k6, v6, k7, v7, k8, v8, k9, v9));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap<K,​V> of​(K k1,
                                             V v1,
                                             K k2,
                                             V v2,
                                             K k3,
                                             V v3,
                                             K k4,
                                             V v4,
                                             K k5,
                                             V v5,
                                             K k6,
                                             V v6,
                                             K k7,
                                             V v7,
                                             K k8,
                                             V v8,
                                             K k9,
                                             V v9,
                                             K k10,
                                             V v10)
        Returns an unmodifiable map containing ten mappings.
        Type Parameters:
        K - the Map's key type
        V - the Map's value type
        Parameters:
        k1 - the first mapping's key
        v1 - the first mapping's value
        k2 - the second mapping's key
        v2 - the second mapping's value
        k3 - the third mapping's key
        v3 - the third mapping's value
        k4 - the fourth mapping's key
        v4 - the fourth mapping's value
        k5 - the fifth mapping's key
        v5 - the fifth mapping's value
        k6 - the sixth mapping's key
        v6 - the sixth mapping's value
        k7 - the seventh mapping's key
        v7 - the seventh mapping's value
        k8 - the eighth mapping's key
        v8 - the eighth mapping's value
        k9 - the ninth mapping's key
        v9 - the ninth mapping's value
        k10 - the tenth mapping's key
        v10 - the tenth mapping's value
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any key or value is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyMap<>(
     Map.of(
         k1, v1, k2, v2, k3, v3, k4, v4, k5, v5, k6, v6,
         k7, v7, k8, v8, k9, v9, k10, v10
     ));

      • ofEntries

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
tatic <K,​V> ReadOnlyMap<K,​V> ofEntries​
            (ReadOnlyMap.Entry<? extends K,​? extends V>... entries)
        Returns an unmodifiable map containing keys and values extracted from the given entries. The entries themselves are not stored in the map.

        It is convenient to create the map entries using the ReadOnlyMap.entry() method. For example,

        Example:
         import static Torello.Java.ReadOnly.ReadOnlyMap.entry;

 ReadOnlyMap<Integer,String> map = ReadOnlyMap.ofEntries(
      entry(1, "a"),
      entry(2, "b"),
      entry(3, "c"),
      ...
      entry(26, "z"));
        Type Parameters:
        K - the ReadOnlyMap's key type
        V - the ReadOnlyMap's value type
        Parameters:
        entries - ReadOnlyMap.Entrys containing the keys and values from which the map is populated
        Returns:
        a ReadOnlyMap containing the specified mappings
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate keys
        java.lang.NullPointerException - if any entry, key, or value is null, or if the entries array is null
        See Also:
        Map.entry()
        Code:
        Exact Method Body:
         // *** Java-HTML: This arbitrarily uses TreeMap
 ROTreeMapBuilder<K, V> b = new ROTreeMapBuilder<>();

 for (ReadOnlyMap.Entry<? extends K, ? extends V> e : entries)
     b.put(e.getKey(), e.getValue());

 return b.build();

      • entry

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        static <K,​V> ReadOnlyMap.Entry<K,​V> entry​(K k,
                                                      V v)
        Returns an unmodifiable ReadOnlyMap.Entry containing the given key and value. These entries are suitable for populating ReadOnlyMap instances using the ReadOnlyMap.ofEntries() method.
        Type Parameters:
        K - the key's type
        V - the value's type
        Parameters:
        k - the key
        v - the value
        Returns:
        an Entry containing the specified key and value
        Throws:
        java.lang.NullPointerException - if the key or value is null
        See Also:
        Map.ofEntries()
        Code:
        Exact Method Body:
         // KeyValueHolder checks for nulls
 // return new KeyValueHolder<>(k, v);
 return new EntryImpl<>(Objects.requireNonNull(k), Objects.requireNonNull(v));