Top Description Inners Constructors Methods
com.google.common.collect

public final Class Maps

extends Object
Class Inheritance
Annotations
@GwtCompatible
emulated:true
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkArgument, .Preconditions.checkNotNull, .Predicates.compose, com.google.common.collect.CollectPreconditions.checkEntryNotNull, .CollectPreconditions.checkNonnegative, .NullnessCasts.uncheckedCastNullableTToT, java.util.Collections.singletonMap, .Objects.requireNonNull

Static utility methods pertaining to Map instances (including instances of SortedMap, BiMap, etc.). Also see this class's counterparts Lists, Sets and Queues.

See the Guava User Guide article on Maps.

Authors
Kevin Bourrillion, Mike Bostock, Isaac Shum, Louis Wasserman
Since
2.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
private abstract static class
private static class
private static class
pack-priv abstract static class
private static enum
pack-priv abstract static class
public static interface
Maps.EntryTransformer<
the key type of the input and output entries
K extends @Nullable Object
,
the value type of the input entry
V1 extends @Nullable Object
,
the value type of the output entry
V2 extends @Nullable Object
>

A transformation of the value of a key-value pair, using both key and value as inputs.

pack-priv static class
pack-priv static class
private static class
private static class
private static class
private static class
pack-priv abstract static class
pack-priv static class
pack-priv static class
private static class
pack-priv static class
pack-priv static class
pack-priv static class
private static class
pack-priv static class
private static class
pack-priv static class
pack-priv static class
pack-priv static class
pack-priv static class
pack-priv static class
pack-priv abstract static class
Maps.ViewCachingAbstractMap<K extends @Nullable Object, V extends @Nullable Object>

AbstractMap extension that makes it easy to cache customized keySet, values, and entrySet views.

Constructor Summary

AccessConstructor and Description
private
Maps()

Method Summary

Modifier and TypeMethod and Description
public static <A, B> Converter<A, B>
asConverter(final BiMap<A, B> bimap)

Returns a Converter that converts values using bimap.get(), and whose inverse view converts values using bimap.inverse().get().

pack-priv static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Function<Map.Entry<K, V1>, Map.Entry<K, V2>>
asEntryToEntryFunction(final Maps.EntryTransformer<? super K, ? super V1, V2> transformer)

Views an entry transformer as a function from entries to entries.

pack-priv static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Function<Map.Entry<K, V1>, V2>
asEntryToValueFunction(final Maps.EntryTransformer<? super K, ? super V1, V2> transformer)

Views an entry transformer as a function from Entry to values.

pack-priv static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Maps.EntryTransformer<K, V1, V2>
asEntryTransformer(final Function<? super V1, V2> function)

Views a function as an entry transformer that ignores the entry key.

public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
asMap(Set<K> set, Function<? super K, V> function)

Returns a live Map view whose keys are the contents of set and whose values are computed on demand using function.

public static <K extends @Nullable Object, V extends @Nullable Object> SortedMap<K, V>
asMap(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.

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>
asMap(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.

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> Iterator<Map.Entry<K, V>>
asMapEntryIterator(Set<K> set, final Function<? super K, V> function)

pack-priv static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Function<V1, V2>
asValueToValueFunction(final Maps.EntryTransformer<? super K, V1, V2> transformer, final K key)

pack-priv static int
capacity(int expectedSize)

Returns a capacity that is sufficient to keep the map from being resized as long as it grows no larger than expectedSize and the load factor is ≥ its default (0.75).

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> boolean

Returns:

true if c contains o
containsEntryImpl
(Collection<Map.Entry<K, V>>
the delegate (unwrapped) collection of map entries
c
,
Object
the object that might be contained in c
o
)

Implements Collection.contains safely for forwarding collections of map entries.

pack-priv static boolean
containsKeyImpl(Map<?, ?> map, Object key)

An admittedly inefficient implementation of Map#containsKey.

pack-priv static boolean
containsValueImpl(Map<?, ?> map, Object value)

An implementation of Map#containsValue.

public static <K extends @Nullable Object, V extends @Nullable Object> MapDifference<K, V>

Returns:

the difference between the two maps
difference
(Map<? extends K, ? extends V>
the map to treat as the "left" map for purposes of comparison
left
,
Map<? extends K, ? extends V>
the map to treat as the "right" map for purposes of comparison
right
)

Computes the difference between two maps.

public static <K extends @Nullable Object, V extends @Nullable Object> MapDifference<K, V>

Returns:

the difference between the two maps
difference
(Map<? extends K, ? extends V>
the map to treat as the "left" map for purposes of comparison
left
,
Map<? extends K, ? extends V>
the map to treat as the "right" map for purposes of comparison
right
,
Equivalence<? super @NonNull V>
the equivalence relationship to use to compare values
valueEquivalence
)

Computes the difference between two maps.

public static <K extends @Nullable Object, V extends @Nullable Object> SortedMapDifference<K, V>

Returns:

the difference between the two maps
difference
(SortedMap<K, ? extends V>
the map to treat as the "left" map for purposes of comparison
left
,
Map<? extends K, ? extends V>
the map to treat as the "right" map for purposes of comparison
right
)

Computes the difference between two sorted maps, using the comparator of the left map, or Ordering.natural() if the left map uses the natural ordering of its elements.

private static <K extends @Nullable Object, V extends @Nullable Object> void
doDifference(Map<? extends K, ? extends V> left, Map<? extends K, ? extends V> right, Equivalence<? super @NonNull V> valueEquivalence, Map<K, V> onlyOnLeft, Map<K, V> onlyOnRight, Map<K, V> onBoth, Map<K, MapDifference.ValueDifference<V>> differences)

pack-priv static boolean
equalsImpl(Map<?, ?> map, Object object)

An implementation of Map#equals.

public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
filterEntries(Map<K, V> unfiltered, Predicate<? super Map.Entry<K, V>> entryPredicate)

Returns a map containing the mappings in unfiltered that satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> SortedMap<K, V>
filterEntries(SortedMap<K, V> unfiltered, Predicate<? super Map.Entry<K, V>> entryPredicate)

Returns a sorted map containing the mappings in unfiltered that satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>
filterEntries(NavigableMap<K, V> unfiltered, Predicate<? super Map.Entry<K, V>> entryPredicate)

Returns a sorted map containing the mappings in unfiltered that satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>
filterEntries(BiMap<K, V> unfiltered, Predicate<? super Map.Entry<K, V>> entryPredicate)

Returns a bimap containing the mappings in unfiltered that satisfy a predicate.

private static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
filterFiltered(Maps.AbstractFilteredMap<K, V> map, Predicate<? super Map.Entry<K, V>> entryPredicate)

Support clear(), removeAll(), and retainAll() when filtering a filtered map.

private static <K extends @Nullable Object, V extends @Nullable Object> SortedMap<K, V>
filterFiltered(Maps.FilteredEntrySortedMap<K, V> map, Predicate<? super Map.Entry<K, V>> entryPredicate)

Support clear(), removeAll(), and retainAll() when filtering a filtered sorted map.

private static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>
filterFiltered(Maps.FilteredEntryNavigableMap<K, V> map, Predicate<? super Map.Entry<K, V>> entryPredicate)

Support clear(), removeAll(), and retainAll() when filtering a filtered navigable map.

private static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>
filterFiltered(Maps.FilteredEntryBiMap<K, V> map, Predicate<? super Map.Entry<K, V>> entryPredicate)

Support clear(), removeAll(), and retainAll() when filtering a filtered map.

public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
filterKeys(Map<K, V> unfiltered, final Predicate<? super K> keyPredicate)

Returns a map containing the mappings in unfiltered whose keys satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> SortedMap<K, V>
filterKeys(SortedMap<K, V> unfiltered, final Predicate<? super K> keyPredicate)

Returns a sorted map containing the mappings in unfiltered whose keys satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>
filterKeys(NavigableMap<K, V> unfiltered, final Predicate<? super K> keyPredicate)

Returns a navigable map containing the mappings in unfiltered whose keys satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>
filterKeys(BiMap<K, V> unfiltered, final Predicate<? super K> keyPredicate)

Returns a bimap containing the mappings in unfiltered whose keys satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
filterValues(Map<K, V> unfiltered, final Predicate<? super V> valuePredicate)

Returns a map containing the mappings in unfiltered whose values satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> SortedMap<K, V>
filterValues(SortedMap<K, V> unfiltered, final Predicate<? super V> valuePredicate)

Returns a sorted map containing the mappings in unfiltered whose values satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>
filterValues(NavigableMap<K, V> unfiltered, final Predicate<? super V> valuePredicate)

Returns a navigable map containing the mappings in unfiltered whose values satisfy a predicate.

public static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>
filterValues(BiMap<K, V> unfiltered, final Predicate<? super V> valuePredicate)

Returns a bimap containing the mappings in unfiltered whose values satisfy a predicate.

public static ImmutableMap<String, String>

Returns:

an immutable map containing all the entries in properties
fromProperties
(Properties
a Properties object to be converted
properties
)

Creates an ImmutableMap<String, String> from a Properties instance.

public static <K extends @Nullable Object, V extends @Nullable Object> Map.Entry<K, V>
immutableEntry(K
the key to be associated with the returned entry
key
,
V
the value to be associated with the returned entry
value
)

Returns an immutable map entry with the specified key and value.

public static <K extends Enum<K>, V> ImmutableMap<K, V>

Returns:

an immutable map containing those entries
immutableEnumMap
(Map<K, ? extends V>
the map to make an immutable copy of
map
)

Returns an immutable map instance containing the given entries.

pack-priv static <E> ImmutableMap<E, Integer>
indexMap(Collection<E> list)

Returns a map from the ith element of list to i.

pack-priv static <K extends @Nullable Object> Function<Map.Entry<K, ?>, K>
pack-priv static <K extends @Nullable Object, V extends @Nullable Object> Iterator<K>
keyIterator(Iterator<Map.Entry<K, V>> entryIterator)

pack-priv static <K extends @Nullable Object> K
keyOrNull(Map.Entry<K, ?> entry)

pack-priv static <K extends @Nullable Object> Predicate<Map.Entry<K, ?>>
keyPredicateOnEntries(Predicate<? super K> keyPredicate)

public static <K, V> ConcurrentMap<K, V>
newConcurrentMap()

Creates a new empty ConcurrentHashMap instance.

public static <K extends Enum<K>, V extends @Nullable Object> EnumMap<K, V>

Returns:

a new, empty EnumMap
newEnumMap
(Class<K>
the key type for this map
type
)

Creates an EnumMap instance.

public static <K extends Enum<K>, V extends @Nullable Object> EnumMap<K, V>

Returns:

a new EnumMap initialized with the mappings from map
newEnumMap
(Map<K, ? extends V>
the map from which to initialize this EnumMap
map
)

Creates an EnumMap with the same mappings as the specified map.

public static <K extends @Nullable Object, V extends @Nullable Object> HashMap<K, V>

Returns:

a new, empty HashMap
newHashMap
()

Creates a mutable, empty HashMap instance.

public static <K extends @Nullable Object, V extends @Nullable Object> HashMap<K, V>

Returns:

a new HashMap initialized with the mappings from map
newHashMap
(Map<? extends K, ? extends V>
the mappings to be placed in the new map
map
)

Creates a mutable HashMap instance with the same mappings as the specified map.

public static <K extends @Nullable Object, V extends @Nullable Object> HashMap<K, V>

Returns:

a new, empty HashMap with enough capacity to hold expectedSize entries without resizing
newHashMapWithExpectedSize
(int
the number of entries you expect to add to the returned map
expectedSize
)

Creates a HashMap instance, with a high enough "initial capacity" that it should hold expectedSize elements without growth.

public static <K extends @Nullable Object, V extends @Nullable Object> IdentityHashMap<K, V>

Returns:

a new, empty IdentityHashMap
newIdentityHashMap
()

Creates an IdentityHashMap instance.

public static <K extends @Nullable Object, V extends @Nullable Object> LinkedHashMap<K, V>

Returns:

a new, empty LinkedHashMap
newLinkedHashMap
()

Creates a mutable, empty, insertion-ordered LinkedHashMap instance.

public static <K extends @Nullable Object, V extends @Nullable Object> LinkedHashMap<K, V>

Returns:

a new, LinkedHashMap initialized with the mappings from map
newLinkedHashMap
(Map<? extends K, ? extends V>
the mappings to be placed in the new map
map
)

Creates a mutable, insertion-ordered LinkedHashMap instance with the same mappings as the specified map.

public static <K extends @Nullable Object, V extends @Nullable Object> LinkedHashMap<K, V>

Returns:

a new, empty LinkedHashMap with enough capacity to hold expectedSize entries without resizing
newLinkedHashMapWithExpectedSize
(int
the number of entries you expect to add to the returned map
expectedSize
)

Creates a LinkedHashMap instance, with a high enough "initial capacity" that it should hold expectedSize elements without growth.

public static <K extends Comparable<T>, V extends @Nullable Object> TreeMap<K, V>

Returns:

a new, empty TreeMap
newTreeMap
()

Creates a mutable, empty TreeMap instance using the natural ordering of its elements.

public static <K extends @Nullable Object, V extends @Nullable Object> TreeMap<K, V>

Returns:

a new TreeMap initialized with the mappings from map and using the comparator of map
newTreeMap
(SortedMap<K, ? extends V>
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
map
)

Creates a mutable TreeMap instance with the same mappings as the specified map and using the same ordering as the specified map.

public static <C extends @Nullable Object, K extends C, V extends @Nullable Object> TreeMap<K, V>

Returns:

a new, empty TreeMap
newTreeMap
(Comparator<C>
the comparator to sort the keys with
comparator
)

Creates a mutable, empty TreeMap instance using the given comparator.

pack-priv static <E extends @Nullable Object> Comparator<? super E>
orNaturalOrder(Comparator<? super E> comparator)

Returns the specified comparator if not null; otherwise returns Ordering.natural().

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> void
putAllImpl(Map<K, V> self, Map<? extends K, ? extends V> map)

An implementation of Map#putAll.

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> boolean

Returns:

true if c was changed
removeEntryImpl
(Collection<Map.Entry<K, V>>
the delegate (unwrapped) collection of map entries
c
,
Object
the object to remove from c
o
)

Implements Collection.remove safely for forwarding collections of map entries.

private static <E extends @Nullable Object> NavigableSet<E>
private static <E extends @Nullable Object> Set<E>
removeOnlySet(final Set<E> set)

private static <E extends @Nullable Object> SortedSet<E>
pack-priv static boolean
safeContainsKey(Map<?, ?> map, Object key)

Delegates to Map#containsKey.

pack-priv static <V extends @Nullable Object> V
safeGet(Map<?, V> map, Object key)

Delegates to Map#get.

pack-priv static <V extends @Nullable Object> V
safeRemove(Map<?, V> map, Object key)

Delegates to Map#remove.

public static <K extends Comparable<? super K>, V extends @Nullable Object> NavigableMap<K, V>
subMap(NavigableMap<K, V> map, Range<K> range)

Returns a view of the portion of map whose keys are contained by range.

public static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>

Returns:

a synchronized view of the specified bimap
synchronizedBiMap
(BiMap<K, V>
the bimap to be wrapped in a synchronized view
bimap
)

Returns a synchronized (thread-safe) bimap backed by the specified bimap.

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>

Returns:

a synchronized view of the specified navigable map.
synchronizedNavigableMap
(NavigableMap<K, V>
the navigable map to be "wrapped" in a synchronized navigable map.
navigableMap
)

Returns a synchronized (thread-safe) navigable map backed by the specified navigable map.

public static <T extends @Nullable Object, K extends Enum<K>, V> Collector<T, ?, ImmutableMap<K, V>>
toImmutableEnumMap(Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction)

Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

public static <T extends @Nullable Object, K extends Enum<K>, V> Collector<T, ?, ImmutableMap<K, V>>
toImmutableEnumMap(Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction, BinaryOperator<V> mergeFunction)

Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

public static <K, V> ImmutableMap<K, V>
toMap(Iterable<K> keys, Function<? super K, V> valueFunction)

Returns an immutable map whose keys are the distinct elements of keys and whose value for each key was computed by valueFunction.

public static <K, V> ImmutableMap<K, V>
toMap(Iterator<K> keys, Function<? super K, V> valueFunction)

Returns an immutable map whose keys are the distinct elements of keys and whose value for each key was computed by valueFunction.

pack-priv static String
toStringImpl(Map<?, ?> map)

An implementation of Map#toString.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Map<K, V2>
transformEntries(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.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> SortedMap<K, V2>
transformEntries(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.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> NavigableMap<K, V2>
transformEntries(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.

pack-priv static <V2 extends @Nullable Object, K extends @Nullable Object, V1 extends @Nullable Object> Map.Entry<K, V2>
transformEntry(final Maps.EntryTransformer<? super K, ? super V1, V2> transformer, final Map.Entry<K, V1> entry)

Returns a view of an entry transformed by the specified transformer.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> Map<K, V2>
transformValues(Map<K, V1> fromMap, Function<? super V1, V2> function)

Returns a view of a map where each value is transformed by a function.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> SortedMap<K, V2>
transformValues(SortedMap<K, V1> fromMap, Function<? super V1, V2> function)

Returns a view of a sorted map where each value is transformed by a function.

public static <K extends @Nullable Object, V1 extends @Nullable Object, V2 extends @Nullable Object> NavigableMap<K, V2>
transformValues(NavigableMap<K, V1> fromMap, Function<? super V1, V2> function)

Returns a view of a navigable map where each value is transformed by a function.

public static <K, V> ImmutableMap<K, V>

Returns:

a map mapping the result of evaluating the function keyFunction on each value in the input collection to that value
uniqueIndex
(Iterable<V>
the values to use when constructing the Map
values
,
Function<? super V, K>
the function used to produce the key for each value
keyFunction
)

Returns a map with the given values, indexed by keys derived from those values.

public static <K, V> ImmutableMap<K, V>

Returns:

a map mapping the result of evaluating the function keyFunction on each value in the input collection to that value
uniqueIndex
(Iterator<V>
the values to use when constructing the Map
values
,
Function<? super V, K>
the function used to produce the key for each value
keyFunction
)

Returns a map with the given values, indexed by keys derived from those values.

private static <K, V> ImmutableMap<K, V>
uniqueIndex(Iterator<V> values, Function<? super V, K> keyFunction, ImmutableMap.Builder<K, V> builder)

public static <K extends @Nullable Object, V extends @Nullable Object> BiMap<K, V>

Returns:

an unmodifiable view of the specified bimap
unmodifiableBiMap
(BiMap<? extends K, ? extends V>
the bimap for which an unmodifiable view is to be returned
bimap
)

Returns an unmodifiable view of the specified bimap.

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> Map.Entry<K, V>

Returns:

an unmodifiable view of the entry
unmodifiableEntry
(final Map.Entry<? extends K, ? extends V>
the entry for which to return an unmodifiable view
entry
)

Returns an unmodifiable view of the specified map entry.

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> UnmodifiableIterator<Map.Entry<K, V>>
unmodifiableEntryIterator(final Iterator<Map.Entry<K, V>> entryIterator)

pack-priv static <K extends @Nullable Object, V extends @Nullable Object> Set<Map.Entry<K, V>>

Returns:

an unmodifiable view of the entries
unmodifiableEntrySet
(Set<Map.Entry<K, V>>
the entries for which to return an unmodifiable view
entrySet
)

Returns an unmodifiable view of the specified set of entries.

private static <K extends @Nullable Object, V extends @Nullable Object> Map<K, V>
unmodifiableMap(Map<K, ? extends V> map)

public static <K extends @Nullable Object, V extends @Nullable Object> NavigableMap<K, V>

Returns:

an unmodifiable view of the specified navigable map
unmodifiableNavigableMap
(NavigableMap<K, ? extends V>
the navigable map for which an unmodifiable view is to be returned
map
)

Returns an unmodifiable view of the specified navigable map.

private static <K extends @Nullable Object, V extends @Nullable Object> Map.Entry<K, V>
unmodifiableOrNull(Map.Entry<K, ? extends V> entry)

pack-priv static <V extends @Nullable Object> Function<Map.Entry<?, V>, V>
pack-priv static <K extends @Nullable Object, V extends @Nullable Object> Iterator<V>
valueIterator(Iterator<Map.Entry<K, V>> entryIterator)

pack-priv static <V extends @Nullable Object> V
valueOrNull(Map.Entry<?, V> entry)

pack-priv static <V extends @Nullable Object> Predicate<Map.Entry<?, V>>
valuePredicateOnEntries(Predicate<? super V> valuePredicate)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait