@GwtCompatible(emulated=true) public final class Multimaps extends Object
Multimap
.
See the Guava User Guide article on Multimaps
.
Modifier and Type | Method and Description |
---|---|
static <K,V> Map<K,List<V>> |
asMap(ListMultimap<K,V> multimap)
|
static <K,V> Map<K,Collection<V>> |
asMap(Multimap<K,V> multimap)
Returns
multimap.asMap() . |
static <K,V> Map<K,Set<V>> |
asMap(SetMultimap<K,V> multimap)
|
static <K,V> Map<K,SortedSet<V>> |
asMap(SortedSetMultimap<K,V> multimap)
Returns
multimap.asMap() , with its type corrected from Map<K, Collection<V>> to Map<K, SortedSet<V>> . |
static <K,V> Multimap<K,V> |
filterEntries(Multimap<K,V> unfiltered,
Predicate<? super Map.Entry<K,V>> entryPredicate)
Returns a multimap containing the mappings in
unfiltered that satisfy a predicate. |
static <K,V> SetMultimap<K,V> |
filterEntries(SetMultimap<K,V> unfiltered,
Predicate<? super Map.Entry<K,V>> entryPredicate)
Returns a multimap containing the mappings in
unfiltered that satisfy a predicate. |
static <K,V> ListMultimap<K,V> |
filterKeys(ListMultimap<K,V> unfiltered,
Predicate<? super K> keyPredicate)
Returns a multimap containing the mappings in
unfiltered whose keys satisfy a
predicate. |
static <K,V> Multimap<K,V> |
filterKeys(Multimap<K,V> unfiltered,
Predicate<? super K> keyPredicate)
Returns a multimap containing the mappings in
unfiltered whose keys satisfy a
predicate. |
static <K,V> SetMultimap<K,V> |
filterKeys(SetMultimap<K,V> unfiltered,
Predicate<? super K> keyPredicate)
Returns a multimap containing the mappings in
unfiltered whose keys satisfy a
predicate. |
static <K,V> Multimap<K,V> |
filterValues(Multimap<K,V> unfiltered,
Predicate<? super V> valuePredicate)
Returns a multimap containing the mappings in
unfiltered whose values satisfy a
predicate. |
static <K,V> SetMultimap<K,V> |
filterValues(SetMultimap<K,V> unfiltered,
Predicate<? super V> valuePredicate)
Returns a multimap containing the mappings in
unfiltered whose values satisfy a
predicate. |
static <T,K,V,M extends Multimap<K,V>> |
flatteningToMultimap(Function<? super T,? extends K> keyFunction,
Function<? super T,? extends Stream<? extends V>> valueFunction,
Supplier<M> multimapSupplier)
Returns a
Collector accumulating entries into a Multimap generated from the
specified supplier. |
static <K,V> SetMultimap<K,V> |
forMap(Map<K,V> map)
Returns a multimap view of the specified map.
|
static <K,V> ImmutableListMultimap<K,V> |
index(Iterable<V> values,
Function<? super V,K> keyFunction)
Creates an index
ImmutableListMultimap that contains the results of applying a
specified function to each item in an Iterable of values. |
static <K,V> ImmutableListMultimap<K,V> |
index(Iterator<V> values,
Function<? super V,K> keyFunction)
Creates an index
ImmutableListMultimap that contains the results of applying a
specified function to each item in an Iterator of values. |
static <K,V,M extends Multimap<K,V>> |
invertFrom(Multimap<? extends V,? extends K> source,
M dest)
Copies each key-value mapping in
source into dest , with its key and value
reversed. |
static <K,V> ListMultimap<K,V> |
newListMultimap(Map<K,Collection<V>> map,
Supplier<? extends List<V>> factory)
Creates a new
ListMultimap that uses the provided map and factory. |
static <K,V> Multimap<K,V> |
newMultimap(Map<K,Collection<V>> map,
Supplier<? extends Collection<V>> factory)
Creates a new
Multimap backed by map , whose internal value collections are
generated by factory . |
static <K,V> SetMultimap<K,V> |
newSetMultimap(Map<K,Collection<V>> map,
Supplier<? extends Set<V>> factory)
Creates a new
SetMultimap that uses the provided map and factory. |
static <K,V> SortedSetMultimap<K,V> |
newSortedSetMultimap(Map<K,Collection<V>> map,
Supplier<? extends SortedSet<V>> factory)
Creates a new
SortedSetMultimap that uses the provided map and factory. |
static <K,V> ListMultimap<K,V> |
synchronizedListMultimap(ListMultimap<K,V> multimap)
Returns a synchronized (thread-safe)
ListMultimap backed by the specified multimap. |
static <K,V> Multimap<K,V> |
synchronizedMultimap(Multimap<K,V> multimap)
Returns a synchronized (thread-safe) multimap backed by the specified multimap.
|
static <K,V> SetMultimap<K,V> |
synchronizedSetMultimap(SetMultimap<K,V> multimap)
Returns a synchronized (thread-safe)
SetMultimap backed by the specified multimap. |
static <K,V> SortedSetMultimap<K,V> |
synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap)
Returns a synchronized (thread-safe)
SortedSetMultimap backed by the specified
multimap. |
static <T,K,V,M extends Multimap<K,V>> |
toMultimap(Function<? super T,? extends K> keyFunction,
Function<? super T,? extends V> valueFunction,
Supplier<M> multimapSupplier)
Returns a
Collector accumulating entries into a Multimap generated from the
specified supplier. |
static <K,V1,V2> ListMultimap<K,V2> |
transformEntries(ListMultimap<K,V1> fromMap,
Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a
ListMultimap whose values are derived from the original multimap's
entries. |
static <K,V1,V2> Multimap<K,V2> |
transformEntries(Multimap<K,V1> fromMap,
Maps.EntryTransformer<? super K,? super V1,V2> transformer)
Returns a view of a multimap whose values are derived from the original multimap's entries.
|
static <K,V1,V2> ListMultimap<K,V2> |
transformValues(ListMultimap<K,V1> fromMultimap,
Function<? super V1,V2> function)
Returns a view of a
ListMultimap where each value is transformed by a function. |
static <K,V1,V2> Multimap<K,V2> |
transformValues(Multimap<K,V1> fromMultimap,
Function<? super V1,V2> function)
Returns a view of a multimap where each value is transformed by a function.
|
static <K,V> ListMultimap<K,V> |
unmodifiableListMultimap(ImmutableListMultimap<K,V> delegate)
Deprecated.
no need to use this
|
static <K,V> ListMultimap<K,V> |
unmodifiableListMultimap(ListMultimap<K,V> delegate)
Returns an unmodifiable view of the specified
ListMultimap . |
static <K,V> Multimap<K,V> |
unmodifiableMultimap(ImmutableMultimap<K,V> delegate)
Deprecated.
no need to use this
|
static <K,V> Multimap<K,V> |
unmodifiableMultimap(Multimap<K,V> delegate)
Returns an unmodifiable view of the specified multimap.
|
static <K,V> SetMultimap<K,V> |
unmodifiableSetMultimap(ImmutableSetMultimap<K,V> delegate)
Deprecated.
no need to use this
|
static <K,V> SetMultimap<K,V> |
unmodifiableSetMultimap(SetMultimap<K,V> delegate)
Returns an unmodifiable view of the specified
SetMultimap . |
static <K,V> SortedSetMultimap<K,V> |
unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate)
Returns an unmodifiable view of the specified
SortedSetMultimap . |
@Beta public static <T,K,V,M extends Multimap<K,V>> Collector<T,?,M> toMultimap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction, Supplier<M> multimapSupplier)
Collector
accumulating entries into a Multimap
generated from the
specified supplier. The keys and values of the entries are the result of applying the provided
mapping functions to the input elements, accumulated in the encounter order of the stream.
Example:
static final ListMultimap<Character, String> FIRST_LETTER_MULTIMAP =
Stream.of("banana", "apple", "carrot", "asparagus", "cherry")
.collect(
toMultimap(
str -> str.charAt(0),
str -> str.substring(1),
MultimapBuilder.treeKeys().arrayListValues()::build));
// is equivalent to
static final ListMultimap<Character, String> FIRST_LETTER_MULTIMAP;
static {
FIRST_LETTER_MULTIMAP = MultimapBuilder.treeKeys().arrayListValues().build();
FIRST_LETTER_MULTIMAP.put('b', "anana");
FIRST_LETTER_MULTIMAP.put('a', "pple");
FIRST_LETTER_MULTIMAP.put('a', "sparagus");
FIRST_LETTER_MULTIMAP.put('c', "arrot");
FIRST_LETTER_MULTIMAP.put('c', "herry");
}
@Beta public static <T,K,V,M extends Multimap<K,V>> Collector<T,?,M> flatteningToMultimap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends Stream<? extends V>> valueFunction, Supplier<M> multimapSupplier)
Collector
accumulating entries into a Multimap
generated from the
specified supplier. Each input element is mapped to a key and a stream of values, each of which
are put into the resulting Multimap
, in the encounter order of the stream and the
encounter order of the streams of values.
Example:
static final ListMultimap<Character, Character> FIRST_LETTER_MULTIMAP =
Stream.of("banana", "apple", "carrot", "asparagus", "cherry")
.collect(
flatteningToMultimap(
str -> str.charAt(0),
str -> str.substring(1).chars().mapToObj(c -> (char) c),
MultimapBuilder.linkedHashKeys().arrayListValues()::build));
// is equivalent to
static final ListMultimap<Character, Character> FIRST_LETTER_MULTIMAP;
static {
FIRST_LETTER_MULTIMAP = MultimapBuilder.linkedHashKeys().arrayListValues().build();
FIRST_LETTER_MULTIMAP.putAll('b', Arrays.asList('a', 'n', 'a', 'n', 'a'));
FIRST_LETTER_MULTIMAP.putAll('a', Arrays.asList('p', 'p', 'l', 'e'));
FIRST_LETTER_MULTIMAP.putAll('c', Arrays.asList('a', 'r', 'r', 'o', 't'));
FIRST_LETTER_MULTIMAP.putAll('a', Arrays.asList('s', 'p', 'a', 'r', 'a', 'g', 'u', 's'));
FIRST_LETTER_MULTIMAP.putAll('c', Arrays.asList('h', 'e', 'r', 'r', 'y'));
}
public static <K,V> Multimap<K,V> newMultimap(Map<K,Collection<V>> map, Supplier<? extends Collection<V>> factory)
Multimap
backed by map
, whose internal value collections are
generated by factory
.
Warning: do not use this method when the collections returned by factory
implement either List
or Set
! Use the more specific method newListMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.List<V>>)
, newSetMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.Set<V>>)
or newSortedSetMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.SortedSet<V>>)
instead, to avoid
very surprising behavior from Multimap.equals(java.lang.Object)
.
The factory
-generated and map
classes determine the multimap iteration
order. They also specify the behavior of the equals
, hashCode
, and toString
methods for the multimap and its returned views. However, the multimap's get
method returns instances of a different class than factory.get()
does.
The multimap is serializable if map
, factory
, the collections generated by
factory
, and the multimap contents are all serializable.
The multimap is not threadsafe when any concurrent operations update the multimap, even if
map
and the instances generated by factory
are. Concurrent read operations will
work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedMultimap(com.google.common.collect.Multimap<K, V>)
.
Call this method only when the simpler methods ArrayListMultimap.create()
, HashMultimap.create()
, LinkedHashMultimap.create()
, LinkedListMultimap.create()
, TreeMultimap.create()
, and TreeMultimap.create(Comparator, Comparator)
won't suffice.
Note: the multimap assumes complete ownership over of map
and the collections
returned by factory
. Those objects should not be manually updated and they should not
use soft, weak, or phantom references.
map
- place to store the mapping from each key to its corresponding valuesfactory
- supplier of new, empty collections that will each hold all values for a given
keyIllegalArgumentException
- if map
is not emptypublic static <K,V> ListMultimap<K,V> newListMultimap(Map<K,Collection<V>> map, Supplier<? extends List<V>> factory)
ListMultimap
that uses the provided map and factory. It can generate a
multimap based on arbitrary Map
and List
classes.
The factory
-generated and map
classes determine the multimap iteration
order. They also specify the behavior of the equals
, hashCode
, and toString
methods for the multimap and its returned views. The multimap's get
, removeAll
, and replaceValues
methods return RandomAccess
lists if the factory
does. However, the multimap's get
method returns instances of a different class than
does factory.get()
.
The multimap is serializable if map
, factory
, the lists generated by factory
, and the multimap contents are all serializable.
The multimap is not threadsafe when any concurrent operations update the multimap, even if
map
and the instances generated by factory
are. Concurrent read operations will
work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedListMultimap(com.google.common.collect.ListMultimap<K, V>)
.
Call this method only when the simpler methods ArrayListMultimap.create()
and LinkedListMultimap.create()
won't suffice.
Note: the multimap assumes complete ownership over of map
and the lists returned by
factory
. Those objects should not be manually updated, they should be empty when
provided, and they should not use soft, weak, or phantom references.
map
- place to store the mapping from each key to its corresponding valuesfactory
- supplier of new, empty lists that will each hold all values for a given keyIllegalArgumentException
- if map
is not emptypublic static <K,V> SetMultimap<K,V> newSetMultimap(Map<K,Collection<V>> map, Supplier<? extends Set<V>> factory)
SetMultimap
that uses the provided map and factory. It can generate a
multimap based on arbitrary Map
and Set
classes.
The factory
-generated and map
classes determine the multimap iteration
order. They also specify the behavior of the equals
, hashCode
, and toString
methods for the multimap and its returned views. However, the multimap's get
method returns instances of a different class than factory.get()
does.
The multimap is serializable if map
, factory
, the sets generated by factory
, and the multimap contents are all serializable.
The multimap is not threadsafe when any concurrent operations update the multimap, even if
map
and the instances generated by factory
are. Concurrent read operations will
work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedSetMultimap(com.google.common.collect.SetMultimap<K, V>)
.
Call this method only when the simpler methods HashMultimap.create()
, LinkedHashMultimap.create()
, TreeMultimap.create()
, and TreeMultimap.create(Comparator, Comparator)
won't suffice.
Note: the multimap assumes complete ownership over of map
and the sets returned by
factory
. Those objects should not be manually updated and they should not use soft,
weak, or phantom references.
map
- place to store the mapping from each key to its corresponding valuesfactory
- supplier of new, empty sets that will each hold all values for a given keyIllegalArgumentException
- if map
is not emptypublic static <K,V> SortedSetMultimap<K,V> newSortedSetMultimap(Map<K,Collection<V>> map, Supplier<? extends SortedSet<V>> factory)
SortedSetMultimap
that uses the provided map and factory. It can generate
a multimap based on arbitrary Map
and SortedSet
classes.
The factory
-generated and map
classes determine the multimap iteration
order. They also specify the behavior of the equals
, hashCode
, and toString
methods for the multimap and its returned views. However, the multimap's get
method returns instances of a different class than factory.get()
does.
The multimap is serializable if map
, factory
, the sets generated by factory
, and the multimap contents are all serializable.
The multimap is not threadsafe when any concurrent operations update the multimap, even if
map
and the instances generated by factory
are. Concurrent read operations will
work correctly. To allow concurrent update operations, wrap the multimap with a call to synchronizedSortedSetMultimap(com.google.common.collect.SortedSetMultimap<K, V>)
.
Call this method only when the simpler methods TreeMultimap.create()
and TreeMultimap.create(Comparator, Comparator)
won't suffice.
Note: the multimap assumes complete ownership over of map
and the sets returned by
factory
. Those objects should not be manually updated and they should not use soft,
weak, or phantom references.
map
- place to store the mapping from each key to its corresponding valuesfactory
- supplier of new, empty sorted sets that will each hold all values for a given
keyIllegalArgumentException
- if map
is not empty@CanIgnoreReturnValue public static <K,V,M extends Multimap<K,V>> M invertFrom(Multimap<? extends V,? extends K> source, M dest)
source
into dest
, with its key and value
reversed.
If source
is an ImmutableMultimap
, consider using ImmutableMultimap.inverse()
instead.
source
- any multimapdest
- the multimap to copy into; usually emptydest
public static <K,V> Multimap<K,V> synchronizedMultimap(Multimap<K,V> multimap)
It is imperative that the user manually synchronize on the returned multimap when accessing any of its collection views:
Multimap<K, V> multimap = Multimaps.synchronizedMultimap(
HashMultimap.<K, V>create());
...
Collection<V> values = multimap.get(key); // Needn't be in synchronized block
...
synchronized (multimap) { // Synchronizing on multimap, not values!
Iterator<V> i = values.iterator(); // Must be in synchronized block
while (i.hasNext()) {
foo(i.next());
}
}
Failure to follow this advice may result in non-deterministic behavior.
Note that the generated multimap's Multimap.removeAll(java.lang.Object)
and Multimap.replaceValues(K, java.lang.Iterable<? extends V>)
methods return collections that aren't synchronized.
The returned multimap will be serializable if the specified multimap is serializable.
multimap
- the multimap to be wrapped in a synchronized viewpublic static <K,V> Multimap<K,V> unmodifiableMultimap(Multimap<K,V> delegate)
UnsupportedOperationException
.
The returned multimap will be serializable if the specified multimap is serializable.
delegate
- the multimap for which an unmodifiable view is to be returned@Deprecated public static <K,V> Multimap<K,V> unmodifiableMultimap(ImmutableMultimap<K,V> delegate)
public static <K,V> SetMultimap<K,V> synchronizedSetMultimap(SetMultimap<K,V> multimap)
SetMultimap
backed by the specified multimap.
You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap<K, V>)
.
The returned multimap will be serializable if the specified multimap is serializable.
multimap
- the multimap to be wrappedpublic static <K,V> SetMultimap<K,V> unmodifiableSetMultimap(SetMultimap<K,V> delegate)
SetMultimap
. Query operations on the
returned multimap "read through" to the specified multimap, and attempts to modify the returned
multimap, either directly or through the multimap's views, result in an UnsupportedOperationException
.
The returned multimap will be serializable if the specified multimap is serializable.
delegate
- the multimap for which an unmodifiable view is to be returned@Deprecated public static <K,V> SetMultimap<K,V> unmodifiableSetMultimap(ImmutableSetMultimap<K,V> delegate)
public static <K,V> SortedSetMultimap<K,V> synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap)
SortedSetMultimap
backed by the specified
multimap.
You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap<K, V>)
.
The returned multimap will be serializable if the specified multimap is serializable.
multimap
- the multimap to be wrappedpublic static <K,V> SortedSetMultimap<K,V> unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate)
SortedSetMultimap
. Query operations on
the returned multimap "read through" to the specified multimap, and attempts to modify the
returned multimap, either directly or through the multimap's views, result in an UnsupportedOperationException
.
The returned multimap will be serializable if the specified multimap is serializable.
delegate
- the multimap for which an unmodifiable view is to be returnedpublic static <K,V> ListMultimap<K,V> synchronizedListMultimap(ListMultimap<K,V> multimap)
ListMultimap
backed by the specified multimap.
You must follow the warnings described in synchronizedMultimap(com.google.common.collect.Multimap<K, V>)
.
multimap
- the multimap to be wrappedpublic static <K,V> ListMultimap<K,V> unmodifiableListMultimap(ListMultimap<K,V> delegate)
ListMultimap
. Query operations on the
returned multimap "read through" to the specified multimap, and attempts to modify the returned
multimap, either directly or through the multimap's views, result in an UnsupportedOperationException
.
The returned multimap will be serializable if the specified multimap is serializable.
delegate
- the multimap for which an unmodifiable view is to be returned@Deprecated public static <K,V> ListMultimap<K,V> unmodifiableListMultimap(ImmutableListMultimap<K,V> delegate)
@Beta public static <K,V> Map<K,List<V>> asMap(ListMultimap<K,V> multimap)
@Beta public static <K,V> Map<K,Set<V>> asMap(SetMultimap<K,V> multimap)
@Beta public static <K,V> Map<K,SortedSet<V>> asMap(SortedSetMultimap<K,V> multimap)
multimap.asMap()
, with its type corrected from Map<K, Collection<V>>
to Map<K, SortedSet<V>>
.@Beta public static <K,V> Map<K,Collection<V>> asMap(Multimap<K,V> multimap)
multimap.asMap()
. This is provided for parity with the other
more strongly-typed asMap()
implementations.public static <K,V> SetMultimap<K,V> forMap(Map<K,V> map)
remove
operation, or through the setValue
operation on a map
entry returned by the iterator), the results of the iteration are undefined.
The multimap supports mapping removal, which removes the corresponding mapping from the map.
It does not support any operations which might add mappings, such as put
, putAll
or replaceValues
.
The returned multimap will be serializable if the specified map is serializable.
map
- the backing map for the returned multimap viewpublic static <K,V1,V2> Multimap<K,V2> transformValues(Multimap<K,V1> fromMultimap, Function<? super V1,V2> function)
Multimap<String, Integer> multimap =
ImmutableSetMultimap.of("a", 2, "b", -3, "b", -3, "a", 4, "c", 6);
Function<Integer, String> square = new Function<Integer, String>() {
public String apply(Integer in) {
return Integer.toString(in * in);
}
};
Multimap<String, String> transformed =
Multimaps.transformValues(multimap, square);
System.out.println(transformed);
... prints {a=[4, 16], b=[9, 9], c=[36]}
.
Changes in the underlying multimap are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying multimap.
It's acceptable for the underlying multimap to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed multimap might contain null values, if the function sometimes gives a null result.
The returned multimap is not thread-safe or serializable, even if the underlying multimap
is. The equals
and hashCode
methods of the returned multimap are meaningless,
since there is not a definition of equals
or hashCode
for general collections,
and get()
will return a general Collection
as opposed to a List
or a
Set
.
The function is applied lazily, invoked when needed. This is necessary for the returned
multimap to be a view, but it means that the function will be applied many times for bulk
operations like Multimap.containsValue(java.lang.Object)
and Multimap.toString()
. For this to
perform well, function
should be fast. To avoid lazy evaluation when the returned
multimap doesn't need to be a view, copy the returned multimap into a new multimap of your
choosing.
public static <K,V1,V2> ListMultimap<K,V2> transformValues(ListMultimap<K,V1> fromMultimap, Function<? super V1,V2> function)
ListMultimap
where each value is transformed by a function. All
other properties of the multimap, such as iteration order, are left intact. For example, the
code:
ListMultimap<String, Integer> multimap
= ImmutableListMultimap.of("a", 4, "a", 16, "b", 9);
Function<Integer, Double> sqrt =
new Function<Integer, Double>() {
public Double apply(Integer in) {
return Math.sqrt((int) in);
}
};
ListMultimap<String, Double> transformed = Multimaps.transformValues(map,
sqrt);
System.out.println(transformed);
... prints {a=[2.0, 4.0], b=[3.0]}
.
Changes in the underlying multimap are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying multimap.
It's acceptable for the underlying multimap to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed multimap might contain null values, if the function sometimes gives a null result.
The returned multimap is not thread-safe or serializable, even if the underlying multimap is.
The function is applied lazily, invoked when needed. This is necessary for the returned
multimap to be a view, but it means that the function will be applied many times for bulk
operations like Multimap.containsValue(java.lang.Object)
and Multimap.toString()
. For this to
perform well, function
should be fast. To avoid lazy evaluation when the returned
multimap doesn't need to be a view, copy the returned multimap into a new multimap of your
choosing.
public static <K,V1,V2> Multimap<K,V2> transformEntries(Multimap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
transformValues(com.google.common.collect.Multimap<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 multimap, such as iteration order, are left intact. For example, the code:
SetMultimap<String, Integer> multimap =
ImmutableSetMultimap.of("a", 1, "a", 4, "b", -6);
EntryTransformer<String, Integer, String> transformer =
new EntryTransformer<String, Integer, String>() {
public String transformEntry(String key, Integer value) {
return (value >= 0) ? key : "no" + key;
}
};
Multimap<String, String> transformed =
Multimaps.transformEntries(multimap, transformer);
System.out.println(transformed);
... prints {a=[a, a], b=[nob]}
.
Changes in the underlying multimap are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying multimap.
It's acceptable for the underlying multimap to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed multimap might contain null values if the transformer sometimes gives a null result.
The returned multimap is not thread-safe or serializable, even if the underlying multimap
is. The equals
and hashCode
methods of the returned multimap are meaningless,
since there is not a definition of equals
or hashCode
for general collections,
and get()
will return a general Collection
as opposed to a List
or a
Set
.
The transformer is applied lazily, invoked when needed. This is necessary for the returned
multimap to be a view, but it means that the transformer will be applied many times for bulk
operations like Multimap.containsValue(java.lang.Object)
and Object.toString()
. For this to perform
well, transformer
should be fast. To avoid lazy evaluation when the returned multimap
doesn't need to be a view, copy the returned multimap into a new multimap of your choosing.
Warning: This method assumes that for any instance k
of EntryTransformer
key type K
, k.equals(k2)
implies that k2
is also of
type K
. Using an EntryTransformer
key type for which this may not hold, such as
ArrayList
, may risk a ClassCastException
when calling methods on the
transformed multimap.
public static <K,V1,V2> ListMultimap<K,V2> transformEntries(ListMultimap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)
ListMultimap
whose values are derived from the original multimap's
entries. In contrast to transformValues(ListMultimap, Function)
, this method's
entry-transformation logic may depend on the key as well as the value.
All other properties of the transformed multimap, such as iteration order, are left intact. For example, the code:
Multimap<String, Integer> multimap =
ImmutableMultimap.of("a", 1, "a", 4, "b", 6);
EntryTransformer<String, Integer, String> transformer =
new EntryTransformer<String, Integer, String>() {
public String transformEntry(String key, Integer value) {
return key + value;
}
};
Multimap<String, String> transformed =
Multimaps.transformEntries(multimap, transformer);
System.out.println(transformed);
... prints {"a"=["a1", "a4"], "b"=["b6"]}
.
Changes in the underlying multimap are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying multimap.
It's acceptable for the underlying multimap to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed multimap might contain null values if the transformer sometimes gives a null result.
The returned multimap is not thread-safe or serializable, even if the underlying multimap is.
The transformer is applied lazily, invoked when needed. This is necessary for the returned
multimap to be a view, but it means that the transformer will be applied many times for bulk
operations like Multimap.containsValue(java.lang.Object)
and Object.toString()
. For this to perform
well, transformer
should be fast. To avoid lazy evaluation when the returned multimap
doesn't need to be a view, copy the returned multimap into a new multimap of your choosing.
Warning: This method assumes that for any instance k
of EntryTransformer
key type K
, k.equals(k2)
implies that k2
is also of
type K
. Using an EntryTransformer
key type for which this may not hold, such as
ArrayList
, may risk a ClassCastException
when calling methods on the
transformed multimap.
public static <K,V> ImmutableListMultimap<K,V> index(Iterable<V> values, Function<? super V,K> keyFunction)
ImmutableListMultimap
that contains the results of applying a
specified function to each item in an Iterable
of values. Each value will be stored as
a value in the resulting multimap, yielding a multimap with the same size as the input
iterable. The key used to store that value in the multimap will be the result of calling the
function on that value. The resulting multimap is created as an immutable snapshot. In the
returned multimap, keys appear in the order they are first encountered, and the values
corresponding to each key appear in the same order as they are encountered.
For example,
List<String> badGuys =
Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
Function<String, Integer> stringLengthFunction = ...;
Multimap<Integer, String> index =
Multimaps.index(badGuys, stringLengthFunction);
System.out.println(index);
prints
{4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}
The returned multimap is serializable if its keys and values are all serializable.
values
- the values to use when constructing the ImmutableListMultimap
keyFunction
- the function used to produce the key for each valueImmutableListMultimap
mapping the result of evaluating the function keyFunction
on each value in the input collection to that valueNullPointerException
- if any element of values
is null
, or if keyFunction
produces null
for any keypublic static <K,V> ImmutableListMultimap<K,V> index(Iterator<V> values, Function<? super V,K> keyFunction)
ImmutableListMultimap
that contains the results of applying a
specified function to each item in an Iterator
of values. Each value will be stored as
a value in the resulting multimap, yielding a multimap with the same size as the input
iterator. The key used to store that value in the multimap will be the result of calling the
function on that value. The resulting multimap is created as an immutable snapshot. In the
returned multimap, keys appear in the order they are first encountered, and the values
corresponding to each key appear in the same order as they are encountered.
For example,
List<String> badGuys =
Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
Function<String, Integer> stringLengthFunction = ...;
Multimap<Integer, String> index =
Multimaps.index(badGuys.iterator(), stringLengthFunction);
System.out.println(index);
prints
{4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}
The returned multimap is serializable if its keys and values are all serializable.
values
- the values to use when constructing the ImmutableListMultimap
keyFunction
- the function used to produce the key for each valueImmutableListMultimap
mapping the result of evaluating the function keyFunction
on each value in the input collection to that valueNullPointerException
- if any element of values
is null
, or if keyFunction
produces null
for any keypublic static <K,V> Multimap<K,V> filterKeys(Multimap<K,V> unfiltered, Predicate<? super K> keyPredicate)
unfiltered
whose keys satisfy a
predicate. The returned multimap is a live view of unfiltered
; changes to one affect
the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a key that doesn't
satisfy the predicate, the multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose keys satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: keyPredicate
must be consistent with equals, as documented at
Predicate.apply(T)
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
public static <K,V> SetMultimap<K,V> filterKeys(SetMultimap<K,V> unfiltered, Predicate<? super K> keyPredicate)
unfiltered
whose keys satisfy a
predicate. The returned multimap is a live view of unfiltered
; changes to one affect
the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a key that doesn't
satisfy the predicate, the multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose keys satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: keyPredicate
must be consistent with equals, as documented at
Predicate.apply(T)
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
public static <K,V> ListMultimap<K,V> filterKeys(ListMultimap<K,V> unfiltered, Predicate<? super K> keyPredicate)
unfiltered
whose keys satisfy a
predicate. The returned multimap is a live view of unfiltered
; changes to one affect
the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a key that doesn't
satisfy the predicate, the multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose keys satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: keyPredicate
must be consistent with equals, as documented at
Predicate.apply(T)
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
public static <K,V> Multimap<K,V> filterValues(Multimap<K,V> unfiltered, Predicate<? super V> valuePredicate)
unfiltered
whose values satisfy a
predicate. The returned multimap is a live view of unfiltered
; changes to one affect
the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a value that doesn't
satisfy the predicate, the multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose value satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: valuePredicate
must be consistent with equals, as documented
at Predicate.apply(T)
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
public static <K,V> SetMultimap<K,V> filterValues(SetMultimap<K,V> unfiltered, Predicate<? super V> valuePredicate)
unfiltered
whose values satisfy a
predicate. The returned multimap is a live view of unfiltered
; changes to one affect
the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a value that doesn't
satisfy the predicate, the multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose value satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: valuePredicate
must be consistent with equals, as documented
at Predicate.apply(T)
. Do not provide a predicate such as Predicates.instanceOf(ArrayList.class)
, which is inconsistent with equals.
public static <K,V> Multimap<K,V> filterEntries(Multimap<K,V> unfiltered, Predicate<? super Map.Entry<K,V>> entryPredicate)
unfiltered
that satisfy a predicate. The
returned multimap is a live view of unfiltered
; changes to one affect the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a key/value pair that
doesn't satisfy the predicate, multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose keys satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: entryPredicate
must be consistent with equals, as documented
at Predicate.apply(T)
.
public static <K,V> SetMultimap<K,V> filterEntries(SetMultimap<K,V> unfiltered, Predicate<? super Map.Entry<K,V>> entryPredicate)
unfiltered
that satisfy a predicate. The
returned multimap is a live view of unfiltered
; changes to one affect the other.
The resulting multimap's views have iterators that don't support remove()
, but all
other methods are supported by the multimap and its views. When adding a key/value pair that
doesn't satisfy the predicate, multimap's put()
, putAll()
, and replaceValues()
methods throw an IllegalArgumentException
.
When methods such as removeAll()
and clear()
are called on the filtered
multimap or its views, only mappings whose keys satisfy the filter will be removed from the
underlying multimap.
The returned multimap isn't threadsafe or serializable, even if unfiltered
is.
Many of the filtered multimap's methods, such as size()
, iterate across every
key/value mapping in the underlying multimap and determine which satisfy the filter. When a
live view is not needed, it may be faster to copy the filtered multimap and use the
copy.
Warning: entryPredicate
must be consistent with equals, as documented
at Predicate.apply(T)
.
Copyright © 2010–2019. All rights reserved.