Class Maps
- java.lang.Object
-
- com.google.common.collect.Maps
-
@GwtCompatible(emulated=true) public final class Maps extends java.lang.Object
Static utility methods pertaining toMap
instances (including instances ofSortedMap
,BiMap
, etc.). Also see this class's counterpartsLists
,Sets
andQueues
.See the Guava User Guide article on
Maps
.- Since:
- 2.0
- Author:
- Kevin Bourrillion, Mike Bostock, Isaac Shum, Louis Wasserman
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
Maps.EntryTransformer<K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
A transformation of the value of a key-value pair, using both key and value as inputs.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <A,B>
Converter<A,B>asConverter(BiMap<A,B> bimap)
Returns aConverter
that converts values usingbimap.get()
, and whose inverse view converts values usingbimap.inverse()
.get()
.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>asMap(java.util.NavigableSet<K> set, Function<? super K,V> function)
Returns a view of the navigable set as a map, mapping keys from the set according to the specified function.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.Map<K,V>asMap(java.util.Set<K> set, Function<? super K,V> function)
Returns a liveMap
view whose keys are the contents ofset
and whose values are computed on demand usingfunction
.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.SortedMap<K,V>asMap(java.util.SortedSet<K> set, Function<? super K,V> function)
Returns a view of the sorted set as a map, mapping keys from the set according to the specified function.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
MapDifference<K,V>difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right)
Computes the difference between two maps.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
MapDifference<K,V>difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right, Equivalence<? super @NonNull V> valueEquivalence)
Computes the difference between two maps.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
SortedMapDifference<K,V>difference(java.util.SortedMap<K,? extends V> left, java.util.Map<? extends K,? extends V> right)
Computes the difference between two sorted maps, using the comparator of the left map, orOrdering.natural()
if the left map uses the natural ordering of its elements.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
BiMap<K,V>filterEntries(BiMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a bimap containing the mappings inunfiltered
that satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.Map<K,V>filterEntries(java.util.Map<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a map containing the mappings inunfiltered
that satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>filterEntries(java.util.NavigableMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a sorted map containing the mappings inunfiltered
that satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.SortedMap<K,V>filterEntries(java.util.SortedMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a sorted map containing the mappings inunfiltered
that satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
BiMap<K,V>filterKeys(BiMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a bimap containing the mappings inunfiltered
whose keys satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.Map<K,V>filterKeys(java.util.Map<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a map containing the mappings inunfiltered
whose keys satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>filterKeys(java.util.NavigableMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a navigable map containing the mappings inunfiltered
whose keys satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.SortedMap<K,V>filterKeys(java.util.SortedMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a sorted map containing the mappings inunfiltered
whose keys satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
BiMap<K,V>filterValues(BiMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a bimap containing the mappings inunfiltered
whose values satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.Map<K,V>filterValues(java.util.Map<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a map containing the mappings inunfiltered
whose values satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>filterValues(java.util.NavigableMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a navigable map containing the mappings inunfiltered
whose values satisfy a predicate.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.SortedMap<K,V>filterValues(java.util.SortedMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a sorted map containing the mappings inunfiltered
whose values satisfy a predicate.static ImmutableMap<java.lang.String,java.lang.String>
fromProperties(java.util.Properties properties)
Creates anImmutableMap<String, String>
from aProperties
instance.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.Map.Entry<K,V>immutableEntry(K key, V value)
Returns an immutable map entry with the specified key and value.static <K extends java.lang.Enum<K>,V>
ImmutableMap<K,V>immutableEnumMap(java.util.Map<K,? extends V> map)
Returns an immutable map instance containing the given entries.static <K,V>
java.util.concurrent.ConcurrentMap<K,V>newConcurrentMap()
Creates a new emptyConcurrentHashMap
instance.static <K extends java.lang.Enum<K>,V extends @Nullable java.lang.Object>
java.util.EnumMap<K,V>newEnumMap(java.lang.Class<K> type)
Creates anEnumMap
instance.static <K extends java.lang.Enum<K>,V extends @Nullable java.lang.Object>
java.util.EnumMap<K,V>newEnumMap(java.util.Map<K,? extends V> map)
Creates anEnumMap
with the same mappings as the specified map.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.HashMap<K,V>newHashMap()
Creates a mutable, emptyHashMap
instance.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.HashMap<K,V>newHashMap(java.util.Map<? extends K,? extends V> map)
Creates a mutableHashMap
instance with the same mappings as the specified map.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.HashMap<K,V>newHashMapWithExpectedSize(int expectedSize)
Creates aHashMap
instance, with a high enough "initial capacity" that it should holdexpectedSize
elements without growth.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.IdentityHashMap<K,V>newIdentityHashMap()
Creates anIdentityHashMap
instance.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.LinkedHashMap<K,V>newLinkedHashMap()
Creates a mutable, empty, insertion-orderedLinkedHashMap
instance.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.LinkedHashMap<K,V>newLinkedHashMap(java.util.Map<? extends K,? extends V> map)
Creates a mutable, insertion-orderedLinkedHashMap
instance with the same mappings as the specified map.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.LinkedHashMap<K,V>newLinkedHashMapWithExpectedSize(int expectedSize)
Creates aLinkedHashMap
instance, with a high enough "initial capacity" that it should holdexpectedSize
elements without growth.static <K extends java.lang.Comparable,V extends @Nullable java.lang.Object>
java.util.TreeMap<K,V>newTreeMap()
Creates a mutable, emptyTreeMap
instance using the natural ordering of its elements.static <C extends @Nullable java.lang.Object,K extends C,V extends @Nullable java.lang.Object>
java.util.TreeMap<K,V>newTreeMap(java.util.Comparator<C> comparator)
Creates a mutable, emptyTreeMap
instance using the given comparator.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.TreeMap<K,V>newTreeMap(java.util.SortedMap<K,? extends V> map)
Creates a mutableTreeMap
instance with the same mappings as the specified map and using the same ordering as the specified map.static <K extends java.lang.Comparable<? super K>,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>subMap(java.util.NavigableMap<K,V> map, Range<K> range)
Returns a view of the portion ofmap
whose keys are contained byrange
.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
BiMap<K,V>synchronizedBiMap(BiMap<K,V> bimap)
Returns a synchronized (thread-safe) bimap backed by the specified bimap.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>synchronizedNavigableMap(java.util.NavigableMap<K,V> navigableMap)
Returns a synchronized (thread-safe) navigable map backed by the specified navigable map.static <T extends @Nullable java.lang.Object,K extends java.lang.Enum<K>,V>
java.util.stream.Collector<T,?,ImmutableMap<K,V>>toImmutableEnumMap(java.util.function.Function<? super T,? extends K> keyFunction, java.util.function.Function<? super T,? extends V> valueFunction)
Returns aCollector
that accumulates elements into anImmutableMap
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 extends java.lang.Enum<K>,V>
java.util.stream.Collector<T,?,ImmutableMap<K,V>>toImmutableEnumMap(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 aCollector
that accumulates elements into anImmutableMap
whose keys and values are the result of applying the provided mapping functions to the input elements.static <K,V>
ImmutableMap<K,V>toMap(java.lang.Iterable<K> keys, Function<? super K,V> valueFunction)
Returns an immutable map whose keys are the distinct elements ofkeys
and whose value for each key was computed byvalueFunction
.static <K,V>
ImmutableMap<K,V>toMap(java.util.Iterator<K> keys, Function<? super K,V> valueFunction)
Returns an immutable map whose keys are the distinct elements ofkeys
and whose value for each key was computed byvalueFunction
.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.Map<K,V2>transformEntries(java.util.Map<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a map whose values are derived from the original map's entries.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V2>transformEntries(java.util.NavigableMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a navigable map whose values are derived from the original navigable map's entries.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.SortedMap<K,V2>transformEntries(java.util.SortedMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a sorted map whose values are derived from the original sorted map's entries.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.Map<K,V2>transformValues(java.util.Map<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a map where each value is transformed by a function.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V2>transformValues(java.util.NavigableMap<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a navigable map where each value is transformed by a function.static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object>
java.util.SortedMap<K,V2>transformValues(java.util.SortedMap<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a sorted map where each value is transformed by a function.static <K,V>
ImmutableMap<K,V>uniqueIndex(java.lang.Iterable<V> values, Function<? super V,K> keyFunction)
Returns a map with the givenvalues
, indexed by keys derived from those values.static <K,V>
ImmutableMap<K,V>uniqueIndex(java.util.Iterator<V> values, Function<? super V,K> keyFunction)
Returns a map with the givenvalues
, indexed by keys derived from those values.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
BiMap<K,V>unmodifiableBiMap(BiMap<? extends K,? extends V> bimap)
Returns an unmodifiable view of the specified bimap.static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object>
java.util.NavigableMap<K,V>unmodifiableNavigableMap(java.util.NavigableMap<K,? extends V> map)
Returns an unmodifiable view of the specified navigable map.
-
-
-
Method Detail
-
immutableEnumMap
@GwtCompatible(serializable=true) public static <K extends java.lang.Enum<K>,V> ImmutableMap<K,V> immutableEnumMap(java.util.Map<K,? extends V> map)
Returns an immutable map instance containing the given entries. Internally, the returned map will be backed by anEnumMap
.The iteration order of the returned map follows the enum's iteration order, not the order in which the elements appear in the given map.
- Parameters:
map
- the map to make an immutable copy of- Returns:
- an immutable map containing those entries
- Since:
- 14.0
-
toImmutableEnumMap
public static <T extends @Nullable java.lang.Object,K extends java.lang.Enum<K>,V> java.util.stream.Collector<T,?,ImmutableMap<K,V>> toImmutableEnumMap(java.util.function.Function<? super T,? extends K> keyFunction, java.util.function.Function<? super T,? extends V> valueFunction)
Returns aCollector
that accumulates elements into anImmutableMap
whose keys and values are the result of applying the provided mapping functions to the input elements. The resulting implementation is specialized for enum key types. The returned map and its views will iterate over keys in their enum definition order, not encounter order.If the mapped keys contain duplicates, an
IllegalArgumentException
is thrown when the collection operation is performed. (This differs from theCollector
returned byCollectors.toMap(Function, Function)
, which throws anIllegalStateException
.)- Since:
- 21.0
-
toImmutableEnumMap
public static <T extends @Nullable java.lang.Object,K extends java.lang.Enum<K>,V> java.util.stream.Collector<T,?,ImmutableMap<K,V>> toImmutableEnumMap(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 aCollector
that accumulates elements into anImmutableMap
whose keys and values are the result of applying the provided mapping functions to the input elements. The resulting implementation is specialized for enum key types. The returned map and its views will iterate over keys in their enum definition order, not encounter order.If the mapped keys contain duplicates, the values are merged using the specified merging function.
- Since:
- 21.0
-
newHashMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.HashMap<K,V> newHashMap()
Creates a mutable, emptyHashMap
instance.Note: if mutability is not required, use
ImmutableMap.of()
instead.Note: if
K
is anenum
type, usenewEnumMap(java.lang.Class<K>)
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
HashMap
constructor directly, taking advantage of "diamond" syntax.- Returns:
- a new, empty
HashMap
-
newHashMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.HashMap<K,V> newHashMap(java.util.Map<? extends K,? extends V> map)
Creates a mutableHashMap
instance with the same mappings as the specified map.Note: if mutability is not required, use
ImmutableMap.copyOf(Map)
instead.Note: if
K
is anEnum
type, usenewEnumMap(java.lang.Class<K>)
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
HashMap
constructor directly, taking advantage of "diamond" syntax.- Parameters:
map
- the mappings to be placed in the new map- Returns:
- a new
HashMap
initialized with the mappings frommap
-
newHashMapWithExpectedSize
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.HashMap<K,V> newHashMapWithExpectedSize(int expectedSize)
Creates aHashMap
instance, with a high enough "initial capacity" that it should holdexpectedSize
elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned map.- Parameters:
expectedSize
- the number of entries you expect to add to the returned map- Returns:
- a new, empty
HashMap
with enough capacity to holdexpectedSize
entries without resizing - Throws:
java.lang.IllegalArgumentException
- ifexpectedSize
is negative
-
newLinkedHashMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.LinkedHashMap<K,V> newLinkedHashMap()
Creates a mutable, empty, insertion-orderedLinkedHashMap
instance.Note: if mutability is not required, use
ImmutableMap.of()
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
LinkedHashMap
constructor directly, taking advantage of "diamond" syntax.- Returns:
- a new, empty
LinkedHashMap
-
newLinkedHashMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.LinkedHashMap<K,V> newLinkedHashMap(java.util.Map<? extends K,? extends V> map)
Creates a mutable, insertion-orderedLinkedHashMap
instance with the same mappings as the specified map.Note: if mutability is not required, use
ImmutableMap.copyOf(Map)
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
LinkedHashMap
constructor directly, taking advantage of "diamond" syntax.- Parameters:
map
- the mappings to be placed in the new map- Returns:
- a new,
LinkedHashMap
initialized with the mappings frommap
-
newLinkedHashMapWithExpectedSize
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.LinkedHashMap<K,V> newLinkedHashMapWithExpectedSize(int expectedSize)
Creates aLinkedHashMap
instance, with a high enough "initial capacity" that it should holdexpectedSize
elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned map.- Parameters:
expectedSize
- the number of entries you expect to add to the returned map- Returns:
- a new, empty
LinkedHashMap
with enough capacity to holdexpectedSize
entries without resizing - Throws:
java.lang.IllegalArgumentException
- ifexpectedSize
is negative- Since:
- 19.0
-
newConcurrentMap
public static <K,V> java.util.concurrent.ConcurrentMap<K,V> newConcurrentMap()
Creates a new emptyConcurrentHashMap
instance.- Since:
- 3.0
-
newTreeMap
public static <K extends java.lang.Comparable,V extends @Nullable java.lang.Object> java.util.TreeMap<K,V> newTreeMap()
Creates a mutable, emptyTreeMap
instance using the natural ordering of its elements.Note: if mutability is not required, use
ImmutableSortedMap.of()
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
TreeMap
constructor directly, taking advantage of "diamond" syntax.- Returns:
- a new, empty
TreeMap
-
newTreeMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.TreeMap<K,V> newTreeMap(java.util.SortedMap<K,? extends V> map)
Creates a mutableTreeMap
instance with the same mappings as the specified map and using the same ordering as the specified map.Note: if mutability is not required, use
ImmutableSortedMap.copyOfSorted(SortedMap)
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
TreeMap
constructor directly, taking advantage of "diamond" syntax.- Parameters:
map
- the sorted map whose mappings are to be placed in the new map and whose comparator is to be used to sort the new map- Returns:
- a new
TreeMap
initialized with the mappings frommap
and using the comparator ofmap
-
newTreeMap
public static <C extends @Nullable java.lang.Object,K extends C,V extends @Nullable java.lang.Object> java.util.TreeMap<K,V> newTreeMap(@CheckForNull java.util.Comparator<C> comparator)
Creates a mutable, emptyTreeMap
instance using the given comparator.Note: if mutability is not required, use
ImmutableSortedMap.orderedBy(comparator).build()
instead.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
TreeMap
constructor directly, taking advantage of "diamond" syntax.- Parameters:
comparator
- the comparator to sort the keys with- Returns:
- a new, empty
TreeMap
-
newEnumMap
public static <K extends java.lang.Enum<K>,V extends @Nullable java.lang.Object> java.util.EnumMap<K,V> newEnumMap(java.lang.Class<K> type)
Creates anEnumMap
instance.- Parameters:
type
- the key type for this map- Returns:
- a new, empty
EnumMap
-
newEnumMap
public static <K extends java.lang.Enum<K>,V extends @Nullable java.lang.Object> java.util.EnumMap<K,V> newEnumMap(java.util.Map<K,? extends V> map)
Creates anEnumMap
with the same mappings as the specified map.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
EnumMap
constructor directly, taking advantage of "diamond" syntax.- Parameters:
map
- the map from which to initialize thisEnumMap
- Returns:
- a new
EnumMap
initialized with the mappings frommap
- Throws:
java.lang.IllegalArgumentException
- ifm
is not anEnumMap
instance and contains no mappings
-
newIdentityHashMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.IdentityHashMap<K,V> newIdentityHashMap()
Creates anIdentityHashMap
instance.Note: this method is now unnecessary and should be treated as deprecated. Instead, use the
IdentityHashMap
constructor directly, taking advantage of "diamond" syntax.- Returns:
- a new, empty
IdentityHashMap
-
difference
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> MapDifference<K,V> difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right)
Computes the difference between two maps. This difference is an immutable snapshot of the state of the maps at the time this method is called. It will never change, even if the maps change at a later time.Since this method uses
HashMap
instances internally, the keys of the supplied maps must be well-behaved with respect toObject.equals(java.lang.Object)
andObject.hashCode()
.Note:If you only need to know whether two maps have the same mappings, call
left.equals(right)
instead of this method.- Parameters:
left
- the map to treat as the "left" map for purposes of comparisonright
- the map to treat as the "right" map for purposes of comparison- Returns:
- the difference between the two maps
-
difference
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> MapDifference<K,V> difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right, Equivalence<? super @NonNull V> valueEquivalence)
Computes the difference between two maps. This difference is an immutable snapshot of the state of the maps at the time this method is called. It will never change, even if the maps change at a later time.Since this method uses
HashMap
instances internally, the keys of the supplied maps must be well-behaved with respect toObject.equals(java.lang.Object)
andObject.hashCode()
.- Parameters:
left
- the map to treat as the "left" map for purposes of comparisonright
- the map to treat as the "right" map for purposes of comparisonvalueEquivalence
- the equivalence relationship to use to compare values- Returns:
- the difference between the two maps
- Since:
- 10.0
-
difference
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> SortedMapDifference<K,V> difference(java.util.SortedMap<K,? extends V> left, java.util.Map<? extends K,? extends V> right)
Computes the difference between two sorted maps, using the comparator of the left map, orOrdering.natural()
if the left map uses the natural ordering of its elements. This difference is an immutable snapshot of the state of the maps at the time this method is called. It will never change, even if the maps change at a later time.Since this method uses
TreeMap
instances internally, the keys of the right map must all compare as distinct according to the comparator of the left map.Note:If you only need to know whether two sorted maps have the same mappings, call
left.equals(right)
instead of this method.- Parameters:
left
- the map to treat as the "left" map for purposes of comparisonright
- the map to treat as the "right" map for purposes of comparison- Returns:
- the difference between the two maps
- Since:
- 11.0
-
asMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.Map<K,V> asMap(java.util.Set<K> set, Function<? super K,V> function)
Returns a liveMap
view whose keys are the contents ofset
and whose values are computed on demand usingfunction
. To get an immutable copy instead, usetoMap(Iterable, Function)
.Specifically, for each
k
in the backing set, the returned map has an entry mappingk
tofunction.apply(k)
. ThekeySet
,values
, andentrySet
views of the returned map iterate in the same order as the backing set.Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.
Warning: If the function rejects
null
, caution is required to make sure the set does not containnull
, because the view cannot stopnull
from being added to the set.Warning: This method assumes that for any instance
k
of key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using a key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the resulting map view.- Since:
- 14.0
-
asMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.SortedMap<K,V> asMap(java.util.SortedSet<K> set, Function<? super K,V> function)
Returns a view of the sorted set as a map, mapping keys from the set according to the specified function.Specifically, for each
k
in the backing set, the returned map has an entry mappingk
tofunction.apply(k)
. ThekeySet
,values
, andentrySet
views of the returned map iterate in the same order as the backing set.Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.
Warning: If the function rejects
null
, caution is required to make sure the set does not containnull
, because the view cannot stopnull
from being added to the set.Warning: This method assumes that for any instance
k
of key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using a key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the resulting map view.- Since:
- 14.0
-
asMap
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> asMap(java.util.NavigableSet<K> set, Function<? super K,V> function)
Returns a view of the navigable set as a map, mapping keys from the set according to the specified function.Specifically, for each
k
in the backing set, the returned map has an entry mappingk
tofunction.apply(k)
. ThekeySet
,values
, andentrySet
views of the returned map iterate in the same order as the backing set.Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.
Warning: If the function rejects
null
, caution is required to make sure the set does not containnull
, because the view cannot stopnull
from being added to the set.Warning: This method assumes that for any instance
k
of key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using a key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the resulting map view.- Since:
- 14.0
-
toMap
public static <K,V> ImmutableMap<K,V> toMap(java.lang.Iterable<K> keys, Function<? super K,V> valueFunction)
Returns an immutable map whose keys are the distinct elements ofkeys
and whose value for each key was computed byvalueFunction
. The map's iteration order is the order of the first appearance of each key inkeys
.When there are multiple instances of a key in
keys
, it is unspecified whethervalueFunction
will be applied to more than one instance of that key and, if it is, which result will be mapped to that key in the returned map.If
keys
is aSet
, a live view can be obtained instead of a copy usingasMap(Set, Function)
.- Throws:
java.lang.NullPointerException
- if any element ofkeys
isnull
, or ifvalueFunction
producesnull
for any key- Since:
- 14.0
-
toMap
public static <K,V> ImmutableMap<K,V> toMap(java.util.Iterator<K> keys, Function<? super K,V> valueFunction)
Returns an immutable map whose keys are the distinct elements ofkeys
and whose value for each key was computed byvalueFunction
. The map's iteration order is the order of the first appearance of each key inkeys
.When there are multiple instances of a key in
keys
, it is unspecified whethervalueFunction
will be applied to more than one instance of that key and, if it is, which result will be mapped to that key in the returned map.- Throws:
java.lang.NullPointerException
- if any element ofkeys
isnull
, or ifvalueFunction
producesnull
for any key- Since:
- 14.0
-
uniqueIndex
@CanIgnoreReturnValue public static <K,V> ImmutableMap<K,V> uniqueIndex(java.lang.Iterable<V> values, Function<? super V,K> keyFunction)
Returns a map with the givenvalues
, indexed by keys derived from those values. In other words, each input value produces an entry in the map whose key is the result of applyingkeyFunction
to that value. These entries appear in the same order as the input values. Example usage:Color red = new Color("red", 255, 0, 0); ... ImmutableSet<Color> allColors = ImmutableSet.of(red, green, blue); ImmutableMap<String, Color> colorForName = uniqueIndex(allColors, c -> c.toString()); assertThat(colorForName).containsEntry("red", red);
If your index may associate multiple values with each key, use
Multimaps.index
.Note: on Java 8 and later, it is usually better to use streams. For example:
import static com.google.common.collect.ImmutableMap.toImmutableMap; ... ImmutableMap<String, Color> colorForName = allColors.stream().collect(toImmutableMap(c -> c.toString(), c -> c));
Streams provide a more standard and flexible API and the lambdas make it clear what the keys and values in the map are.
- Parameters:
values
- the values to use when constructing theMap
keyFunction
- the function used to produce the key for each value- Returns:
- a map mapping the result of evaluating the function
keyFunction
on each value in the input collection to that value - Throws:
java.lang.IllegalArgumentException
- ifkeyFunction
produces the same key for more than one value in the input collectionjava.lang.NullPointerException
- if any element ofvalues
isnull
, or ifkeyFunction
producesnull
for any value
-
uniqueIndex
@CanIgnoreReturnValue public static <K,V> ImmutableMap<K,V> uniqueIndex(java.util.Iterator<V> values, Function<? super V,K> keyFunction)
Returns a map with the givenvalues
, indexed by keys derived from those values. In other words, each input value produces an entry in the map whose key is the result of applyingkeyFunction
to that value. These entries appear in the same order as the input values. Example usage:Color red = new Color("red", 255, 0, 0); ... Iterator<Color> allColors = ImmutableSet.of(red, green, blue).iterator(); Map<String, Color> colorForName = uniqueIndex(allColors, toStringFunction()); assertThat(colorForName).containsEntry("red", red);
If your index may associate multiple values with each key, use
Multimaps.index
.- Parameters:
values
- the values to use when constructing theMap
keyFunction
- the function used to produce the key for each value- Returns:
- a map mapping the result of evaluating the function
keyFunction
on each value in the input collection to that value - Throws:
java.lang.IllegalArgumentException
- ifkeyFunction
produces the same key for more than one value in the input collectionjava.lang.NullPointerException
- if any element ofvalues
isnull
, or ifkeyFunction
producesnull
for any value- Since:
- 10.0
-
fromProperties
@GwtIncompatible public static ImmutableMap<java.lang.String,java.lang.String> fromProperties(java.util.Properties properties)
Creates anImmutableMap<String, String>
from aProperties
instance. Properties normally derive fromMap<Object, Object>
, but they typically contain strings, which is awkward. This method lets you get a plain-old-Map
out of aProperties
.- Parameters:
properties
- aProperties
object to be converted- Returns:
- an immutable map containing all the entries in
properties
- Throws:
java.lang.ClassCastException
- if any key inproperties
is not aString
java.lang.NullPointerException
- if any key or value inproperties
is null
-
immutableEntry
@GwtCompatible(serializable=true) public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.Map.Entry<K,V> immutableEntry(K key, V value)
Returns an immutable map entry with the specified key and value. TheMap.Entry.setValue(V)
operation throws anUnsupportedOperationException
.The returned entry is serializable.
Java 9 users: consider using
java.util.Map.entry(key, value)
if the key and value are non-null and the entry does not need to be serializable.- Parameters:
key
- the key to be associated with the returned entryvalue
- the value to be associated with the returned entry
-
asConverter
public static <A,B> Converter<A,B> asConverter(BiMap<A,B> bimap)
Returns aConverter
that converts values usingbimap.get()
, and whose inverse view converts values usingbimap.inverse()
.get()
.To use a plain
Map
as aFunction
, seeFunctions.forMap(Map)
orFunctions.forMap(Map, Object)
.- Since:
- 16.0
-
synchronizedBiMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> BiMap<K,V> synchronizedBiMap(BiMap<K,V> bimap)
Returns a synchronized (thread-safe) bimap backed by the specified bimap. In order to guarantee serial access, it is critical that all access to the backing bimap is accomplished through the returned bimap.It is imperative that the user manually synchronize on the returned map when accessing any of its collection views:
BiMap<Long, String> map = Maps.synchronizedBiMap( HashBiMap.<Long, String>create()); ... Set<Long> set = map.keySet(); // Needn't be in synchronized block ... synchronized (map) { // Synchronizing on map, not set! Iterator<Long> it = set.iterator(); // Must be in synchronized block while (it.hasNext()) { foo(it.next()); } }
Failure to follow this advice may result in non-deterministic behavior.
The returned bimap will be serializable if the specified bimap is serializable.
- Parameters:
bimap
- the bimap to be wrapped in a synchronized view- Returns:
- a synchronized view of the specified bimap
-
unmodifiableBiMap
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> BiMap<K,V> unmodifiableBiMap(BiMap<? extends K,? extends V> bimap)
Returns an unmodifiable view of the specified bimap. This method allows modules to provide users with "read-only" access to internal bimaps. Query operations on the returned bimap "read through" to the specified bimap, and attempts to modify the returned map, whether direct or via its collection views, result in anUnsupportedOperationException
.The returned bimap will be serializable if the specified bimap is serializable.
- Parameters:
bimap
- the bimap for which an unmodifiable view is to be returned- Returns:
- an unmodifiable view of the specified bimap
-
transformValues
public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.Map<K,V2> transformValues(java.util.Map<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a map where each value is transformed by a function. All other properties of the map, such as iteration order, are left intact. For example, the code:
... printsMap<String, Integer> map = ImmutableMap.of("a", 4, "b", 9); Function<Integer, Double> sqrt = new Function<Integer, Double>() { public Double apply(Integer in) { return Math.sqrt((int) in); } }; Map<String, Double> transformed = Maps.transformValues(map, sqrt); System.out.println(transformed);
{a=2.0, b=3.0}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed map might contain null values, if the function sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The function is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the function will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andMap.toString()
. For this to perform well,function
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.
-
transformValues
public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.SortedMap<K,V2> transformValues(java.util.SortedMap<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a sorted map where each value is transformed by a function. All other properties of the map, such as iteration order, are left intact. For example, the code:
... printsSortedMap<String, Integer> map = ImmutableSortedMap.of("a", 4, "b", 9); Function<Integer, Double> sqrt = new Function<Integer, Double>() { public Double apply(Integer in) { return Math.sqrt((int) in); } }; SortedMap<String, Double> transformed = Maps.transformValues(map, sqrt); System.out.println(transformed);
{a=2.0, b=3.0}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed map might contain null values, if the function sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The function is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the function will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andMap.toString()
. For this to perform well,function
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.- Since:
- 11.0
-
transformValues
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.NavigableMap<K,V2> transformValues(java.util.NavigableMap<K,V1> fromMap, Function<? super V1,V2> function)
Returns a view of a navigable map where each value is transformed by a function. All other properties of the map, such as iteration order, are left intact. For example, the code:
... printsNavigableMap<String, Integer> map = Maps.newTreeMap(); map.put("a", 4); map.put("b", 9); Function<Integer, Double> sqrt = new Function<Integer, Double>() { public Double apply(Integer in) { return Math.sqrt((int) in); } }; NavigableMap<String, Double> transformed = Maps.transformNavigableValues(map, sqrt); System.out.println(transformed);
{a=2.0, b=3.0}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed map might contain null values, if the function sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The function is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the function will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andMap.toString()
. For this to perform well,function
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.- Since:
- 13.0
-
transformEntries
public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.Map<K,V2> transformEntries(java.util.Map<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a map whose values are derived from the original map's entries. In contrast totransformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)
, this method's entry-transformation logic may depend on the key as well as the value.All other properties of the transformed map, such as iteration order, are left intact. For example, the code:
... printsMap<String, Boolean> options = ImmutableMap.of("verbose", true, "sort", false); EntryTransformer<String, Boolean, String> flagPrefixer = new EntryTransformer<String, Boolean, String>() { public String transformEntry(String key, Boolean value) { return value ? key : "no" + key; } }; Map<String, String> transformed = Maps.transformEntries(options, flagPrefixer); System.out.println(transformed);
{verbose=verbose, sort=nosort}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andObject.toString()
. For this to perform well,transformer
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.Warning: This method assumes that for any instance
k
ofEntryTransformer
key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using anEntryTransformer
key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the transformed map.- Since:
- 7.0
-
transformEntries
public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.SortedMap<K,V2> transformEntries(java.util.SortedMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a sorted map whose values are derived from the original sorted map's entries. In contrast totransformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)
, this method's entry-transformation logic may depend on the key as well as the value.All other properties of the transformed map, such as iteration order, are left intact. For example, the code:
... printsMap<String, Boolean> options = ImmutableSortedMap.of("verbose", true, "sort", false); EntryTransformer<String, Boolean, String> flagPrefixer = new EntryTransformer<String, Boolean, String>() { public String transformEntry(String key, Boolean value) { return value ? key : "yes" + key; } }; SortedMap<String, String> transformed = Maps.transformEntries(options, flagPrefixer); System.out.println(transformed);
{sort=yessort, verbose=verbose}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andObject.toString()
. For this to perform well,transformer
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.Warning: This method assumes that for any instance
k
ofEntryTransformer
key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using anEntryTransformer
key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the transformed map.- Since:
- 11.0
-
transformEntries
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V1 extends @Nullable java.lang.Object,V2 extends @Nullable java.lang.Object> java.util.NavigableMap<K,V2> transformEntries(java.util.NavigableMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a navigable map whose values are derived from the original navigable map's entries. In contrast totransformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)
, this method's entry-transformation logic may depend on the key as well as the value.All other properties of the transformed map, such as iteration order, are left intact. For example, the code:
... printsNavigableMap<String, Boolean> options = Maps.newTreeMap(); options.put("verbose", false); options.put("sort", true); EntryTransformer<String, Boolean, String> flagPrefixer = new EntryTransformer<String, Boolean, String>() { public String transformEntry(String key, Boolean value) { return value ? key : ("yes" + key); } }; NavigableMap<String, String> transformed = LabsMaps.transformNavigableEntries(options, flagPrefixer); System.out.println(transformed);
{sort=yessort, verbose=verbose}
.Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.
It's acceptable for the underlying map to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.
The returned map is not thread-safe or serializable, even if the underlying map is.
The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like
Map.containsValue(java.lang.Object)
andObject.toString()
. For this to perform well,transformer
should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.Warning: This method assumes that for any instance
k
ofEntryTransformer
key typeK
,k.equals(k2)
implies thatk2
is also of typeK
. Using anEntryTransformer
key type for which this may not hold, such asArrayList
, may risk aClassCastException
when calling methods on the transformed map.- Since:
- 13.0
-
filterKeys
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.Map<K,V> filterKeys(java.util.Map<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a map containing the mappings inunfiltered
whose keys satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose keys satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
keyPredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
-
filterKeys
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.SortedMap<K,V> filterKeys(java.util.SortedMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a sorted map containing the mappings inunfiltered
whose keys satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose keys satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
keyPredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.- Since:
- 11.0
-
filterKeys
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> filterKeys(java.util.NavigableMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a navigable map containing the mappings inunfiltered
whose keys satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose keys satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
keyPredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.- Since:
- 14.0
-
filterKeys
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> BiMap<K,V> filterKeys(BiMap<K,V> unfiltered, Predicate<? super K> keyPredicate)
Returns a bimap containing the mappings inunfiltered
whose keys satisfy a predicate. The returned bimap is a live view ofunfiltered
; changes to one affect the other.The resulting bimap's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the bimap and its views. When given a key that doesn't satisfy the predicate, the bimap'sput()
,forcePut()
andputAll()
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered bimap or its views, only mappings that satisfy the filter will be removed from the underlying bimap.The returned bimap isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered bimap's methods, such as
size()
, iterate across every key in the underlying bimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered bimap and use the copy.Warning:
entryPredicate
must be consistent with equals , as documented atPredicate.apply(T)
.- Since:
- 14.0
-
filterValues
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.Map<K,V> filterValues(java.util.Map<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a map containing the mappings inunfiltered
whose values satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a value that doesn't satisfy the predicate, the map'sput()
,putAll()
, andMap.Entry.setValue(V)
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose values satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
valuePredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
-
filterValues
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.SortedMap<K,V> filterValues(java.util.SortedMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a sorted map containing the mappings inunfiltered
whose values satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a value that doesn't satisfy the predicate, the map'sput()
,putAll()
, andMap.Entry.setValue(V)
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose values satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
valuePredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.- Since:
- 11.0
-
filterValues
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> filterValues(java.util.NavigableMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a navigable map containing the mappings inunfiltered
whose values satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a value that doesn't satisfy the predicate, the map'sput()
,putAll()
, andMap.Entry.setValue(V)
methods throw anIllegalArgumentException
.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings whose values satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
valuePredicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.- Since:
- 14.0
-
filterValues
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> BiMap<K,V> filterValues(BiMap<K,V> unfiltered, Predicate<? super V> valuePredicate)
Returns a bimap containing the mappings inunfiltered
whose values satisfy a predicate. The returned bimap is a live view ofunfiltered
; changes to one affect the other.The resulting bimap's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the bimap and its views. When given a value that doesn't satisfy the predicate, the bimap'sput()
,forcePut()
andputAll()
methods throw anIllegalArgumentException
. Similarly, the map's entries have aMap.Entry.setValue(V)
method that throws anIllegalArgumentException
when the provided value doesn't satisfy the predicate.When methods such as
removeAll()
andclear()
are called on the filtered bimap or its views, only mappings that satisfy the filter will be removed from the underlying bimap.The returned bimap isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered bimap's methods, such as
size()
, iterate across every value in the underlying bimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered bimap and use the copy.Warning:
entryPredicate
must be consistent with equals , as documented atPredicate.apply(T)
.- Since:
- 14.0
-
filterEntries
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.Map<K,V> filterEntries(java.util.Map<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a map containing the mappings inunfiltered
that satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key/value pair that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
. Similarly, the map's entries have aMap.Entry.setValue(V)
method that throws anIllegalArgumentException
when the existing key and the provided value don't satisfy the predicate.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings that satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
entryPredicate
must be consistent with equals, as documented atPredicate.apply(T)
.
-
filterEntries
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.SortedMap<K,V> filterEntries(java.util.SortedMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a sorted map containing the mappings inunfiltered
that satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key/value pair that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
. Similarly, the map's entries have aMap.Entry.setValue(V)
method that throws anIllegalArgumentException
when the existing key and the provided value don't satisfy the predicate.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings that satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
entryPredicate
must be consistent with equals, as documented atPredicate.apply(T)
.- Since:
- 11.0
-
filterEntries
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> filterEntries(java.util.NavigableMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a sorted map containing the mappings inunfiltered
that satisfy a predicate. The returned map is a live view ofunfiltered
; changes to one affect the other.The resulting map's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the map and its views. When given a key/value pair that doesn't satisfy the predicate, the map'sput()
andputAll()
methods throw anIllegalArgumentException
. Similarly, the map's entries have aMap.Entry.setValue(V)
method that throws anIllegalArgumentException
when the existing key and the provided value don't satisfy the predicate.When methods such as
removeAll()
andclear()
are called on the filtered map or its views, only mappings that satisfy the filter will be removed from the underlying map.The returned map isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered map's methods, such as
size()
, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.Warning:
entryPredicate
must be consistent with equals, as documented atPredicate.apply(T)
.- Since:
- 14.0
-
filterEntries
public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> BiMap<K,V> filterEntries(BiMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)
Returns a bimap containing the mappings inunfiltered
that satisfy a predicate. The returned bimap is a live view ofunfiltered
; changes to one affect the other.The resulting bimap's
keySet()
,entrySet()
, andvalues()
views have iterators that don't supportremove()
, but all other methods are supported by the bimap and its views. When given a key/value pair that doesn't satisfy the predicate, the bimap'sput()
,forcePut()
andputAll()
methods throw anIllegalArgumentException
. Similarly, the map's entries have anMap.Entry.setValue(V)
method that throws anIllegalArgumentException
when the existing key and the provided value don't satisfy the predicate.When methods such as
removeAll()
andclear()
are called on the filtered bimap or its views, only mappings that satisfy the filter will be removed from the underlying bimap.The returned bimap isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered bimap's methods, such as
size()
, iterate across every key/value mapping in the underlying bimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered bimap and use the copy.Warning:
entryPredicate
must be consistent with equals , as documented atPredicate.apply(T)
.- Since:
- 14.0
-
unmodifiableNavigableMap
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> unmodifiableNavigableMap(java.util.NavigableMap<K,? extends V> map)
Returns an unmodifiable view of the specified navigable map. Query operations on the returned map read through to the specified map, and attempts to modify the returned map, whether direct or via its views, result in anUnsupportedOperationException
.The returned navigable map will be serializable if the specified navigable map is serializable.
This method's signature will not permit you to convert a
NavigableMap<? extends K, V>
to aNavigableMap<K, V>
. If it permitted this, the returned map'scomparator()
method might return aComparator<? extends K>
, which works only on a particular subtype ofK
, but promise that it's aComparator<? super K>
, which must work on any type ofK
.- Parameters:
map
- the navigable map for which an unmodifiable view is to be returned- Returns:
- an unmodifiable view of the specified navigable map
- Since:
- 12.0
-
synchronizedNavigableMap
@GwtIncompatible public static <K extends @Nullable java.lang.Object,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> synchronizedNavigableMap(java.util.NavigableMap<K,V> navigableMap)
Returns a synchronized (thread-safe) navigable map backed by the specified navigable map. In order to guarantee serial access, it is critical that all access to the backing navigable map is accomplished through the returned navigable map (or its views).It is imperative that the user manually synchronize on the returned navigable map when iterating over any of its collection views, or the collections views of any of its
descendingMap
,subMap
,headMap
ortailMap
views.NavigableMap<K, V> map = synchronizedNavigableMap(new TreeMap<K, V>()); // Needn't be in synchronized block NavigableSet<K> set = map.navigableKeySet(); synchronized (map) { // Synchronizing on map, not set! Iterator<K> it = set.iterator(); // Must be in synchronized block while (it.hasNext()) { foo(it.next()); } }
or:
NavigableMap<K, V> map = synchronizedNavigableMap(new TreeMap<K, V>()); NavigableMap<K, V> map2 = map.subMap(foo, false, bar, true); // Needn't be in synchronized block NavigableSet<K> set2 = map2.descendingKeySet(); synchronized (map) { // Synchronizing on map, not map2 or set2! Iterator<K> it = set2.iterator(); // Must be in synchronized block while (it.hasNext()) { foo(it.next()); } }
Failure to follow this advice may result in non-deterministic behavior.
The returned navigable map will be serializable if the specified navigable map is serializable.
- Parameters:
navigableMap
- the navigable map to be "wrapped" in a synchronized navigable map.- Returns:
- a synchronized view of the specified navigable map.
- Since:
- 13.0
-
subMap
@GwtIncompatible public static <K extends java.lang.Comparable<? super K>,V extends @Nullable java.lang.Object> java.util.NavigableMap<K,V> subMap(java.util.NavigableMap<K,V> map, Range<K> range)
Returns a view of the portion ofmap
whose keys are contained byrange
.This method delegates to the appropriate methods of
NavigableMap
(namelysubMap()
,tailMap()
, andheadMap()
) to actually construct the view. Consult these methods for a full description of the returned view's behavior.Warning:
Range
s always represent a range of values using the values' natural ordering.NavigableMap
on the other hand can specify a custom ordering via aComparator
, which can violate the natural ordering. Using this method (or in general usingRange
) with unnaturally-ordered maps can lead to unexpected and undefined behavior.- Since:
- 20.0
-
-