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>
@DoNotMock public static class ImmutableMap.Builder<K,V> extends Object
A builder for creating immutable map instances, especiallypublic 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 toLinkedHashMap
. 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
, andkeySet()
andvalues()
respect the same order. If you want a different order, consider usingImmutableSortedMap
to sort by keys, or callorderEntriesByValue(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
-
-
Constructor Summary
Constructors Constructor Description Builder()
Creates a new builder.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ImmutableMap<K,V>
build()
Returns a newly-created immutable map.ImmutableMap<K,V>
buildOrThrow()
Returns a newly-created immutable map, or throws an exception if any key was added more than once.ImmutableMap.Builder<K,V>
orderEntriesByValue(Comparator<? super V> valueComparator)
Configures thisBuilder
to order entries by value according to the specified comparator.ImmutableMap.Builder<K,V>
put(Map.Entry<? extends K,? extends V> entry)
Adds the givenentry
to the map, making it immutable if necessary.ImmutableMap.Builder<K,V>
put(K key, V value)
Associateskey
withvalue
in the built map.ImmutableMap.Builder<K,V>
putAll(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)
Adds all of the given entries to the built map.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.
-
-
-
Constructor Detail
-
Builder
public Builder()
Creates a new builder. The returned builder is equivalent to the builder generated byImmutableMap.builder()
.
-
-
Method Detail
-
put
@CanIgnoreReturnValue public ImmutableMap.Builder<K,V> put(K key, V value)
Associateskey
withvalue
in the built map. Duplicate keys are not allowed, and will causebuild()
to fail.
-
put
@CanIgnoreReturnValue public ImmutableMap.Builder<K,V> put(Map.Entry<? extends K,? extends V> entry)
Adds the givenentry
to the map, making it immutable if necessary. Duplicate keys are not allowed, and will causebuild()
to fail.- Since:
- 11.0
-
putAll
@CanIgnoreReturnValue 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. Duplicate keys are not allowed, and will causebuild()
to fail.- Throws:
NullPointerException
- if any key or value inmap
is null
-
putAll
@CanIgnoreReturnValue @Beta 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. Duplicate keys are not allowed, and will causebuild()
to fail.- Throws:
NullPointerException
- if any key, value, or entry is null- Since:
- 19.0
-
orderEntriesByValue
@CanIgnoreReturnValue @Beta public ImmutableMap.Builder<K,V> orderEntriesByValue(Comparator<? super V> valueComparator)
Configures thisBuilder
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
-
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, unlessorderEntriesByValue(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. Thebuild()
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, unlessorderEntriesByValue(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
-
-