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 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)
         .buildOrThrow();
 

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

By default, a Builder will generate maps that iterate over entries in the order they were inserted into the builder, equivalently to LinkedHashMap. For example, in the above example, WORD_TO_INT.entrySet() is guaranteed to iterate over the entries in the order "one"=1, "two"=2, "three"=3, and keySet() and values() respect the same order. If you want a different order, consider using ImmutableSortedMap to sort by keys, or call orderEntriesByValue(Comparator), which changes this builder to sort entries by value.

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

Since:
2.0
  • Field Details

    • valueComparator

      @CheckForNull Comparator<? super V> valueComparator
    • entries

      Map.Entry<K,V>[] entries
    • size

      int size
    • entriesUsed

      boolean entriesUsed
  • Constructor Details

    • Builder

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

      Builder(int initialCapacity)
  • Method Details

    • ensureCapacity

      private void ensureCapacity(int minCapacity)
    • put

      public ImmutableMap.Builder<K,V> put(K key, V value)
      Associates key with value in the built map. If the same key is put more than once, buildOrThrow() will fail, while buildKeepingLast() will keep the last value put for that key.
    • put

      public ImmutableMap.Builder<K,V> put(Map.Entry<? extends K,? extends V> entry)
      Adds the given entry to the map, making it immutable if necessary. If the same key is put more than once, buildOrThrow() will fail, while buildKeepingLast() will keep the last value put for that key.
      Since:
      11.0
    • putAll

      public ImmutableMap.Builder<K,V> putAll(Map<? extends K,? extends V> map)
      Associates all of the given map's keys and values in the built map. If the same key is put more than once, buildOrThrow() will fail, while buildKeepingLast() will keep the last value put for that key.
      Throws:
      NullPointerException - if any key or value in map is null
    • putAll

      public ImmutableMap.Builder<K,V> putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)
      Adds all of the given entries to the built map. If the same key is put more than once, buildOrThrow() will fail, while buildKeepingLast() will keep the last value put for that key.
      Throws:
      NullPointerException - if any key, value, or entry is null
      Since:
      19.0
    • orderEntriesByValue

      public ImmutableMap.Builder<K,V> orderEntriesByValue(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:
      IllegalStateException - if this method was already called
      Since:
      19.0
    • combine

    • build

      private ImmutableMap<K,V> build(boolean throwIfDuplicateKeys)
    • build

      public ImmutableMap<K,V> build()
      Returns a newly-created immutable map. The iteration order of the returned map is the order in which entries were inserted into the builder, unless orderEntriesByValue(java.util.Comparator<? super V>) was called, in which case entries are sorted by value.

      Prefer the equivalent method buildOrThrow() to make it explicit that the method will throw an exception if there are duplicate keys. The build() method will soon be deprecated.

      Throws:
      IllegalArgumentException - if duplicate keys were added
    • buildOrThrow

      public ImmutableMap<K,V> buildOrThrow()
      Returns a newly-created immutable map, or throws an exception if any key was added more than once. The iteration order of the returned map is the order in which entries were inserted into the builder, unless orderEntriesByValue(java.util.Comparator<? super V>) was called, in which case entries are sorted by value.
      Throws:
      IllegalArgumentException - if duplicate keys were added
      Since:
      31.0
    • buildKeepingLast

      public ImmutableMap<K,V> buildKeepingLast()
      Returns a newly-created immutable map, using the last value for any key that was added more than once. The iteration order of the returned map is the order in which entries were inserted into the builder, unless orderEntriesByValue(java.util.Comparator<? super V>) was called, in which case entries are sorted by value. If a key was added more than once, it appears in iteration order based on the first time it was added, again unless orderEntriesByValue(java.util.Comparator<? super V>) was called.

      In the current implementation, all values associated with a given key are stored in the Builder object, even though only one of them will be used in the built map. If there can be many repeated keys, it may be more space-efficient to use a LinkedHashMap and ImmutableMap.copyOf(Map) rather than ImmutableMap.Builder.

      Since:
      31.1
    • buildJdkBacked

      ImmutableMap<K,V> buildJdkBacked()
    • lastEntryForEachKey

      @CheckForNull private static <K, V> Map.Entry<K,V>[] lastEntryForEachKey(Map.Entry<K,V>[] entries, int size)
      Scans the first size elements of entries looking for duplicate keys. If duplicates are found, a new correctly-sized array is returned with the same elements (up to size), except containing only the last occurrence of each duplicate key. Otherwise null is returned.