public static class ImmutableMap.Builder<K,V>
extends java.lang.Object
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.
Modifier and Type | Field and Description |
---|---|
(package private) java.util.Map.Entry<K,V>[] |
entries |
(package private) boolean |
entriesUsed |
(package private) int |
size |
(package private) java.util.Comparator<? super V> |
valueComparator |
Constructor and Description |
---|
Builder()
Creates a new builder.
|
Builder(int initialCapacity) |
Modifier and Type | Method and Description |
---|---|
ImmutableMap<K,V> |
build()
Returns a newly-created immutable map.
|
private ImmutableMap<K,V> |
build(boolean throwIfDuplicateKeys) |
(package private) ImmutableMap<K,V> |
buildJdkBacked() |
ImmutableMap<K,V> |
buildKeepingLast()
Returns a newly-created immutable map, using the last value for any key that was added more
than once.
|
ImmutableMap<K,V> |
buildOrThrow()
Returns a newly-created immutable map, or throws an exception if any key was added more than
once.
|
(package private) ImmutableMap.Builder<K,V> |
combine(ImmutableMap.Builder<K,V> other) |
private void |
ensureCapacity(int minCapacity) |
private static <K,V> java.util.Map.Entry<K,V>[] |
lastEntryForEachKey(java.util.Map.Entry<K,V>[] entries,
int size) |
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.
|
@CheckForNull java.util.Comparator<? super V> valueComparator
int size
boolean entriesUsed
public Builder()
ImmutableMap.builder()
.Builder(int initialCapacity)
private void ensureCapacity(int minCapacity)
public ImmutableMap.Builder<K,V> put(K key, V value)
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.public ImmutableMap.Builder<K,V> put(java.util.Map.Entry<? extends K,? extends V> entry)
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.public ImmutableMap.Builder<K,V> putAll(java.util.Map<? extends K,? extends V> map)
buildOrThrow()
will fail, while buildKeepingLast()
will keep
the last value put for that key.java.lang.NullPointerException
- if any key or value in map
is nullpublic ImmutableMap.Builder<K,V> putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)
buildOrThrow()
will fail, while buildKeepingLast()
will keep the last value put for
that key.java.lang.NullPointerException
- if any key, value, or entry is nullpublic ImmutableMap.Builder<K,V> orderEntriesByValue(java.util.Comparator<? super V> valueComparator)
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.
java.lang.IllegalStateException
- if this method was already calledImmutableMap.Builder<K,V> combine(ImmutableMap.Builder<K,V> other)
private ImmutableMap<K,V> build(boolean throwIfDuplicateKeys)
public ImmutableMap<K,V> build()
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.
java.lang.IllegalArgumentException
- if duplicate keys were addedpublic ImmutableMap<K,V> buildOrThrow()
orderEntriesByValue(java.util.Comparator<? super V>)
was called, in which case entries are
sorted by value.java.lang.IllegalArgumentException
- if duplicate keys were addedpublic ImmutableMap<K,V> buildKeepingLast()
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
.
ImmutableMap<K,V> buildJdkBacked()
private static <K,V> java.util.Map.Entry<K,V>[] lastEntryForEachKey(java.util.Map.Entry<K,V>[] entries, int size)