ImmutableMap.Builder
Date: 2016-05-24

com.google.common.collect

## Class ImmutableMap.Builder<K,V>

- java.lang.Object
- - com.google.common.collect.ImmutableMap.Builder<K,V>

- Direct Known Subclasses:
    ImmutableBiMap.Builder, ImmutableSortedMap.Builder
  Enclosing class:
    ImmutableMap<K,V>

      public static class ImmutableMap.Builder<K,V>
      extends java.lang.Object

  A builder for creating immutable map instances, especially `public static final` maps ("constant maps"). Example:

         static final ImmutableMap<String, Integer> WORD_TO_INT =
             new ImmutableMap.Builder<String, Integer>()
                 .put("one", 1)
                 .put("two", 2)
                 .put("three", 3)
                 .build();

  For small immutable maps, the `ImmutableMap.of()` methods are even more convenient.

  Builder instances can be reused - it is safe to call `build()` multiple times to build multiple maps in series. Each map is a superset of the maps created before it.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImmutableMap.Builder()` Creates a new builder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableMap<K,V>` | `build()` Returns a newly-created immutable map.
    `ImmutableMap.Builder<K,V>` | `orderEntriesByValue(java.util.Comparator<? super V> valueComparator)` Configures this `Builder` to order entries by value according to the specified comparator.
    `ImmutableMap.Builder<K,V>` | `put(K key, V value)` Associates `key` with `value` in the built map.
    `ImmutableMap.Builder<K,V>` | `put(java.util.Map.Entry<? extends K,? extends V> entry)` Adds the given `entry` to the map, making it immutable if necessary.
    `ImmutableMap.Builder<K,V>` | `putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)` Adds all of the given entries to the built map.
    `ImmutableMap.Builder<K,V>` | `putAll(java.util.Map<? extends K,? extends V> map)` Associates all of the given map's keys and values in the built map.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ImmutableMap.Builder

          public ImmutableMap.Builder()

      Creates a new builder. The returned builder is equivalent to the builder generated by `ImmutableMap.builder()`.

  - ### Method Detail

    - #### put

          public ImmutableMap.Builder<K,V> put(K key,
                                      V value)

      Associates `key` with `value` in the built map. Duplicate keys are not allowed, and will cause `build()` to fail.

    - #### put

          public ImmutableMap.Builder<K,V> put(java.util.Map.Entry<? extends K,? extends V> entry)

      Adds the given `entry` to the map, making it immutable if necessary. Duplicate keys are not allowed, and will cause `build()` to fail.
      Since:
        11.0

    - #### putAll

          public ImmutableMap.Builder<K,V> putAll(java.util.Map<? extends K,? extends V> map)

      Associates all of the given map's keys and values in the built map. Duplicate keys are not allowed, and will cause `build()` to fail.
      Throws:
        `java.lang.NullPointerException` - if any key or value in `map` is null

    - #### putAll

          @Beta
          public ImmutableMap.Builder<K,V> putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)

      Adds all of the given entries to the built map. Duplicate keys are not allowed, and will cause `build()` to fail.
      Throws:
        `java.lang.NullPointerException` - if any key, value, or entry is null
      Since:
        19.0

    - #### orderEntriesByValue

          @Beta
          public ImmutableMap.Builder<K,V> orderEntriesByValue(java.util.Comparator<? super V> valueComparator)

      Configures this `Builder` to order entries by value according to the specified comparator.

      The sort order is stable, that is, if two entries have values that compare as equivalent, the entry that was inserted first will be first in the built map's iteration order.

      Throws:
        `java.lang.IllegalStateException` - if this method was already called
      Since:
        19.0

    - #### build

          public ImmutableMap<K,V> build()

      Returns a newly-created immutable map.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys were added