Class ImmutableMap<K,​V>

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ImmutableMap.Builder<K,​V>
      A builder for creating immutable map instances, especially public static final maps ("constant maps").
      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      ImmutableSetMultimap<K,​V> asMultimap()
      Returns a multimap view of the map.
      static <K,​V>
      ImmutableMap.Builder<K,​V>
      builder()
      Returns a new builder.
      static <K,​V>
      ImmutableMap.Builder<K,​V>
      builderWithExpectedSize​(int expectedSize)
      Returns a new builder, expecting the specified number of entries to be added.
      void clear()
      Deprecated.
      Unsupported operation.
      V compute​(K key, java.util.function.BiFunction<? super K,​? super @Nullable V,​? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      V computeIfAbsent​(K key, java.util.function.Function<? super K,​? extends V> mappingFunction)
      Deprecated.
      Unsupported operation.
      V computeIfPresent​(K key, java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      boolean containsKey​(java.lang.Object key)  
      boolean containsValue​(java.lang.Object value)  
      static <K,​V>
      ImmutableMap<K,​V>
      copyOf​(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,​? extends V>> entries)
      Returns an immutable map containing the specified entries.
      static <K,​V>
      ImmutableMap<K,​V>
      copyOf​(java.util.Map<? extends K,​? extends V> map)
      Returns an immutable map containing the same entries as map.
      ImmutableSet<java.util.Map.Entry<K,​V>> entrySet()
      Returns an immutable set of the mappings in this map.
      boolean equals​(java.lang.Object object)  
      abstract V get​(java.lang.Object key)  
      V getOrDefault​(java.lang.Object key, V defaultValue)  
      int hashCode()  
      boolean isEmpty()  
      ImmutableSet<K> keySet()
      Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.
      V merge​(K key, V value, java.util.function.BiFunction<? super V,​? super V,​? extends V> remappingFunction)
      Deprecated.
      Unsupported operation.
      static <K,​V>
      ImmutableMap<K,​V>
      of()
      Returns the empty map.
      static <K,​V>
      ImmutableMap<K,​V>
      of​(K k1, V v1)
      Returns an immutable map containing a single entry.
      static <K,​V>
      ImmutableMap<K,​V>
      of​(K k1, V v1, K k2, V v2)
      Returns an immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<K,​V>
      of​(K k1, V v1, K k2, V v2, K k3, V v3)
      Returns an immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<K,​V>
      of​(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
      Returns an immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<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 immutable map containing the given entries, in order.
      static <K,​V>
      ImmutableMap<K,​V>
      ofEntries​(java.util.Map.Entry<? extends K,​? extends V>... entries)
      Returns an immutable map containing the given entries, in order.
      V put​(K k, V v)
      Deprecated.
      Unsupported operation.
      void putAll​(java.util.Map<? extends K,​? extends V> map)
      Deprecated.
      Unsupported operation.
      V putIfAbsent​(K key, V value)
      Deprecated.
      Unsupported operation.
      V remove​(java.lang.Object o)
      Deprecated.
      Unsupported operation.
      boolean remove​(java.lang.Object key, java.lang.Object value)
      Deprecated.
      Unsupported operation.
      V replace​(K key, V value)
      Deprecated.
      Unsupported operation.
      boolean replace​(K key, V oldValue, V newValue)
      Deprecated.
      Unsupported operation.
      void replaceAll​(java.util.function.BiFunction<? super K,​? super V,​? extends V> function)
      Deprecated.
      Unsupported operation.
      static <T extends @Nullable java.lang.Object,​K,​V>
      java.util.stream.Collector<T,​?,​ImmutableMap<K,​V>>
      toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyFunction, java.util.function.Function<? super T,​? extends V> valueFunction)
      Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
      static <T extends @Nullable java.lang.Object,​K,​V>
      java.util.stream.Collector<T,​?,​ImmutableMap<K,​V>>
      toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyFunction, java.util.function.Function<? super T,​? extends V> valueFunction, java.util.function.BinaryOperator<V> mergeFunction)
      Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
      java.lang.String toString()  
      ImmutableCollection<V> values()
      Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.Map

        forEach, size
    • Method Detail

      • toImmutableMap

        public static <T extends @Nullable java.lang.Object,​K,​V> java.util.stream.Collector<T,​?,​ImmutableMap<K,​V>> toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyFunction,
                                                                                                                                                                java.util.function.Function<? super T,​? extends V> valueFunction)
        Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements. Entries appear in the result ImmutableMap in encounter order.

        If the mapped keys contain duplicates (according to Object.equals(Object), an IllegalArgumentException is thrown when the collection operation is performed. (This differs from the Collector returned by Collectors.toMap(Function, Function), which throws an IllegalStateException.)

        Since:
        21.0
      • toImmutableMap

        public static <T extends @Nullable java.lang.Object,​K,​V> java.util.stream.Collector<T,​?,​ImmutableMap<K,​V>> toImmutableMap​(java.util.function.Function<? super T,​? extends K> keyFunction,
                                                                                                                                                                java.util.function.Function<? super T,​? extends V> valueFunction,
                                                                                                                                                                java.util.function.BinaryOperator<V> mergeFunction)
        Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

        If the mapped keys contain duplicates (according to Object.equals(Object)), the values are merged using the specified merging function. Entries will appear in the encounter order of the first occurrence of the key.

        Since:
        21.0
      • of

        public static <K,​V> ImmutableMap<K,​V> of()
        Returns the empty map. This map behaves and performs comparably to Collections.emptyMap(), and is preferable mainly for consistency and maintainability of your code.

        Performance note: the instance returned is a singleton.

      • of

        public static <K,​V> ImmutableMap<K,​V> of​(K k1,
                                                             V v1)
        Returns an immutable map containing a single entry. This map behaves and performs comparably to Collections.singletonMap(K, V) but will not accept a null key or value. It is preferable mainly for consistency and maintainability of your code.
      • of

        public static <K,​V> ImmutableMap<K,​V> of​(K k1,
                                                             V v1,
                                                             K k2,
                                                             V v2)
        Returns an immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
      • of

        public static <K,​V> ImmutableMap<K,​V> of​(K k1,
                                                             V v1,
                                                             K k2,
                                                             V v2,
                                                             K k3,
                                                             V v3)
        Returns an immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
      • of

        public static <K,​V> ImmutableMap<K,​V> of​(K k1,
                                                             V v1,
                                                             K k2,
                                                             V v2,
                                                             K k3,
                                                             V v3,
                                                             K k4,
                                                             V v4)
        Returns an immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • of

        public static <K,​V> ImmutableMap<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 immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • ofEntries

        @SafeVarargs
        public static <K,​V> ImmutableMap<K,​V> ofEntries​(java.util.Map.Entry<? extends K,​? extends V>... entries)
        Returns an immutable map containing the given entries, in order.
        Throws:
        java.lang.IllegalArgumentException - if duplicate keys are provided
        Since:
        31.0
      • builderWithExpectedSize

        @Beta
        public static <K,​V> ImmutableMap.Builder<K,​V> builderWithExpectedSize​(int expectedSize)
        Returns a new builder, expecting the specified number of entries to be added.

        If expectedSize is exactly the number of entries added to the builder before ImmutableMap.Builder.build(boolean) is called, the builder is likely to perform better than an unsized builder() would have.

        It is not specified if any performance benefits apply if expectedSize is close to, but not exactly, the number of entries added to the builder.

        Since:
        23.1
      • copyOf

        public static <K,​V> ImmutableMap<K,​V> copyOf​(java.util.Map<? extends K,​? extends V> map)
        Returns an immutable map containing the same entries as map. The returned map iterates over entries in the same order as the entrySet of the original map. If map somehow contains entries with duplicate keys (for example, if it is a SortedMap whose comparator is not consistent with equals), the results of this method are undefined.

        Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

        Throws:
        java.lang.NullPointerException - if any key or value in map is null
      • copyOf

        @Beta
        public static <K,​V> ImmutableMap<K,​V> copyOf​(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,​? extends V>> entries)
        Returns an immutable map containing the specified entries. The returned map iterates over entries in the same order as the original iterable.
        Throws:
        java.lang.NullPointerException - if any key, value, or entry is null
        java.lang.IllegalArgumentException - if two entries have the same key
        Since:
        19.0
      • put

        @CanIgnoreReturnValue
        @Deprecated
        @CheckForNull
        public final V put​(K k,
                           V v)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        put in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • putIfAbsent

        @CanIgnoreReturnValue
        @Deprecated
        @CheckForNull
        public final V putIfAbsent​(K key,
                                   V value)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        putIfAbsent in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • replace

        @Deprecated
        public final boolean replace​(K key,
                                     V oldValue,
                                     V newValue)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        replace in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • replace

        @Deprecated
        @CheckForNull
        public final V replace​(K key,
                               V value)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        replace in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • computeIfAbsent

        @Deprecated
        public final V computeIfAbsent​(K key,
                                       java.util.function.Function<? super K,​? extends V> mappingFunction)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        computeIfAbsent in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • computeIfPresent

        @Deprecated
        public final V computeIfPresent​(K key,
                                        java.util.function.BiFunction<? super K,​? super V,​? extends V> remappingFunction)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        computeIfPresent in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • compute

        @Deprecated
        public final V compute​(K key,
                               java.util.function.BiFunction<? super K,​? super @Nullable V,​? extends V> remappingFunction)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        compute in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • merge

        @Deprecated
        public final V merge​(K key,
                             V value,
                             java.util.function.BiFunction<? super V,​? super V,​? extends V> remappingFunction)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        merge in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • putAll

        @Deprecated
        public final void putAll​(java.util.Map<? extends K,​? extends V> map)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        putAll in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • replaceAll

        @Deprecated
        public final void replaceAll​(java.util.function.BiFunction<? super K,​? super V,​? extends V> function)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        replaceAll in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • remove

        @Deprecated
        @CheckForNull
        public final V remove​(@CheckForNull
                              java.lang.Object o)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        remove in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • remove

        @Deprecated
        public final boolean remove​(@CheckForNull
                                    java.lang.Object key,
                                    @CheckForNull
                                    java.lang.Object value)
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        remove in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • clear

        @Deprecated
        public final void clear()
        Deprecated.
        Unsupported operation.
        Guaranteed to throw an exception and leave the map unmodified.
        Specified by:
        clear in interface java.util.Map<K,​V>
        Throws:
        java.lang.UnsupportedOperationException - always
      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface java.util.Map<K,​V>
      • containsKey

        public boolean containsKey​(@CheckForNull
                                   java.lang.Object key)
        Specified by:
        containsKey in interface java.util.Map<K,​V>
      • containsValue

        public boolean containsValue​(@CheckForNull
                                     java.lang.Object value)
        Specified by:
        containsValue in interface java.util.Map<K,​V>
      • getOrDefault

        @CheckForNull
        public final V getOrDefault​(@CheckForNull
                                    java.lang.Object key,
                                    @CheckForNull
                                    V defaultValue)
        Specified by:
        getOrDefault in interface java.util.Map<K,​V>
        Since:
        21.0 (but only since 23.5 in the Android flavor). Note, however, that Java 8 users can call this method with any version and flavor of Guava.
      • entrySet

        public ImmutableSet<java.util.Map.Entry<K,​V>> entrySet()
        Returns an immutable set of the mappings in this map. The iteration order is specified by the method used to create this map. Typically, this is insertion order.
        Specified by:
        entrySet in interface java.util.Map<K,​V>
      • keySet

        public ImmutableSet<KkeySet()
        Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.
        Specified by:
        keySet in interface java.util.Map<K,​V>
      • values

        public ImmutableCollection<Vvalues()
        Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.
        Specified by:
        values in interface java.util.Map<K,​V>
      • equals

        public boolean equals​(@CheckForNull
                              java.lang.Object object)
        Specified by:
        equals in interface java.util.Map<K,​V>
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Specified by:
        hashCode in interface java.util.Map<K,​V>
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object