com.google.common.collect.Multimaps Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* Copyright (C) 2007 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.collect;
import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.collect.CollectPreconditions.checkNonnegative;
import static com.google.common.collect.CollectPreconditions.checkRemove;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.GwtIncompatible;
import com.google.common.base.Function;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import com.google.common.base.Supplier;
import com.google.common.collect.Maps.EntryTransformer;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import com.google.j2objc.annotations.Weak;
import com.google.j2objc.annotations.WeakOuter;
import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.util.AbstractCollection;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.SortedSet;
import java.util.Spliterator;
import java.util.function.Consumer;
import java.util.stream.Collector;
import java.util.stream.Stream;
import javax.annotation.Nullable;
/**
* Provides static methods acting on or generating a {@code Multimap}.
*
* See the Guava User Guide article on
* {@code Multimaps}.
*
* @author Jared Levy
* @author Robert Konigsberg
* @author Mike Bostock
* @author Louis Wasserman
* @since 2.0
*/
@GwtCompatible(emulated = true)
public final class Multimaps {
private Multimaps() {}
/**
* Returns a {@code Collector} accumulating entries into a {@code 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:
*
*
{@code
* static final ListMultimap 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 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");
* }
* }
*
* @since 21.0
*/
@Beta
public static > Collector toMultimap(
java.util.function.Function keyFunction,
java.util.function.Function valueFunction,
java.util.function.Supplier multimapSupplier) {
checkNotNull(keyFunction);
checkNotNull(valueFunction);
checkNotNull(multimapSupplier);
return Collector.of(
multimapSupplier,
(multimap, input) -> multimap.put(keyFunction.apply(input), valueFunction.apply(input)),
(multimap1, multimap2) -> {
multimap1.putAll(multimap2);
return multimap1;
});
}
/**
* Returns a {@code Collector} accumulating entries into a {@code 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 {@code Multimap}, in the encounter order of the stream and the
* encounter order of the streams of values.
*
* Example:
*
*
{@code
* static final ListMultimap 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 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'));
* }
* }
*
* @since 21.0
*/
@Beta
public static > Collector flatteningToMultimap(
java.util.function.Function keyFunction,
java.util.function.Function> valueFunction,
java.util.function.Supplier multimapSupplier) {
checkNotNull(keyFunction);
checkNotNull(valueFunction);
checkNotNull(multimapSupplier);
return Collector.of(
multimapSupplier,
(multimap, input) -> {
K key = keyFunction.apply(input);
Collection valuesForKey = multimap.get(key);
valueFunction.apply(input).forEachOrdered(valuesForKey::add);
},
(multimap1, multimap2) -> {
multimap1.putAll(multimap2);
return multimap1;
});
}
/**
* Creates a new {@code Multimap} backed by {@code map}, whose internal value collections are
* generated by {@code factory}.
*
* Warning: do not use this method when the collections returned by {@code factory}
* implement either {@link List} or {@code Set}! Use the more specific method {@link
* #newListMultimap}, {@link #newSetMultimap} or {@link #newSortedSetMultimap} instead, to avoid
* very surprising behavior from {@link Multimap#equals}.
*
*
The {@code factory}-generated and {@code map} classes determine the multimap iteration
* order. They also specify the behavior of the {@code equals}, {@code hashCode}, and {@code
* toString} methods for the multimap and its returned views. However, the multimap's {@code get}
* method returns instances of a different class than {@code factory.get()} does.
*
*
The multimap is serializable if {@code map}, {@code factory}, the collections generated by
* {@code factory}, and the multimap contents are all serializable.
*
*
The multimap is not threadsafe when any concurrent operations update the multimap, even if
* {@code map} and the instances generated by {@code factory} are. Concurrent read operations will
* work correctly. To allow concurrent update operations, wrap the multimap with a call to {@link
* #synchronizedMultimap}.
*
*
Call this method only when the simpler methods {@link ArrayListMultimap#create()}, {@link
* HashMultimap#create()}, {@link LinkedHashMultimap#create()}, {@link
* LinkedListMultimap#create()}, {@link TreeMultimap#create()}, and {@link
* TreeMultimap#create(Comparator, Comparator)} won't suffice.
*
*
Note: the multimap assumes complete ownership over of {@code map} and the collections
* returned by {@code factory}. Those objects should not be manually updated and they should not
* use soft, weak, or phantom references.
*
* @param map place to store the mapping from each key to its corresponding values
* @param factory supplier of new, empty collections that will each hold all values for a given
* key
* @throws IllegalArgumentException if {@code map} is not empty
*/
public static Multimap newMultimap(
Map> map, final Supplier> factory) {
return new CustomMultimap<>(map, factory);
}
private static class CustomMultimap extends AbstractMapBasedMultimap {
transient Supplier> factory;
CustomMultimap(Map> map, Supplier> factory) {
super(map);
this.factory = checkNotNull(factory);
}
@Override
protected Collection createCollection() {
return factory.get();
}
// can't use Serialization writeMultimap and populateMultimap methods since
// there's no way to generate the empty backing map.
/** @serialData the factory and the backing map */
@GwtIncompatible // java.io.ObjectOutputStream
private void writeObject(ObjectOutputStream stream) throws IOException {
stream.defaultWriteObject();
stream.writeObject(factory);
stream.writeObject(backingMap());
}
@GwtIncompatible // java.io.ObjectInputStream
@SuppressWarnings("unchecked") // reading data stored by writeObject
private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
stream.defaultReadObject();
factory = (Supplier>) stream.readObject();
Map> map = (Map>) stream.readObject();
setMap(map);
}
@GwtIncompatible // java serialization not supported
private static final long serialVersionUID = 0;
}
/**
* Creates a new {@code ListMultimap} that uses the provided map and factory.
* It can generate a multimap based on arbitrary {@link Map} and {@link List}
* classes.
*
* The {@code factory}-generated and {@code map} classes determine the
* multimap iteration order. They also specify the behavior of the
* {@code equals}, {@code hashCode}, and {@code toString} methods for the
* multimap and its returned views. The multimap's {@code get}, {@code
* removeAll}, and {@code replaceValues} methods return {@code RandomAccess}
* lists if the factory does. However, the multimap's {@code get} method
* returns instances of a different class than does {@code factory.get()}.
*
*
The multimap is serializable if {@code map}, {@code factory}, the
* lists generated by {@code factory}, and the multimap contents are all
* serializable.
*
*
The multimap is not threadsafe when any concurrent operations update the
* multimap, even if {@code map} and the instances generated by
* {@code factory} are. Concurrent read operations will work correctly. To
* allow concurrent update operations, wrap the multimap with a call to
* {@link #synchronizedListMultimap}.
*
*
Call this method only when the simpler methods
* {@link ArrayListMultimap#create()} and {@link LinkedListMultimap#create()}
* won't suffice.
*
*
Note: the multimap assumes complete ownership over of {@code map} and
* the lists returned by {@code factory}. Those objects should not be manually
* updated, they should be empty when provided, and they should not use soft,
* weak, or phantom references.
*
* @param map place to store the mapping from each key to its corresponding
* values
* @param factory supplier of new, empty lists that will each hold all values
* for a given key
* @throws IllegalArgumentException if {@code map} is not empty
*/
public static ListMultimap newListMultimap(
Map> map, final Supplier> factory) {
return new CustomListMultimap<>(map, factory);
}
private static class CustomListMultimap extends AbstractListMultimap {
transient Supplier> factory;
CustomListMultimap(Map> map, Supplier> factory) {
super(map);
this.factory = checkNotNull(factory);
}
@Override
protected List createCollection() {
return factory.get();
}
/** @serialData the factory and the backing map */
@GwtIncompatible // java.io.ObjectOutputStream
private void writeObject(ObjectOutputStream stream) throws IOException {
stream.defaultWriteObject();
stream.writeObject(factory);
stream.writeObject(backingMap());
}
@GwtIncompatible // java.io.ObjectInputStream
@SuppressWarnings("unchecked") // reading data stored by writeObject
private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
stream.defaultReadObject();
factory = (Supplier>) stream.readObject();
Map> map = (Map>) stream.readObject();
setMap(map);
}
@GwtIncompatible // java serialization not supported
private static final long serialVersionUID = 0;
}
/**
* Creates a new {@code SetMultimap} that uses the provided map and factory.
* It can generate a multimap based on arbitrary {@link Map} and {@link Set}
* classes.
*
* The {@code factory}-generated and {@code map} classes determine the
* multimap iteration order. They also specify the behavior of the
* {@code equals}, {@code hashCode}, and {@code toString} methods for the
* multimap and its returned views. However, the multimap's {@code get}
* method returns instances of a different class than {@code factory.get()}
* does.
*
*
The multimap is serializable if {@code map}, {@code factory}, the
* sets generated by {@code factory}, and the multimap contents are all
* serializable.
*
*
The multimap is not threadsafe when any concurrent operations update the
* multimap, even if {@code map} and the instances generated by
* {@code factory} are. Concurrent read operations will work correctly. To
* allow concurrent update operations, wrap the multimap with a call to
* {@link #synchronizedSetMultimap}.
*
*
Call this method only when the simpler methods
* {@link HashMultimap#create()}, {@link LinkedHashMultimap#create()},
* {@link TreeMultimap#create()}, and
* {@link TreeMultimap#create(Comparator, Comparator)} won't suffice.
*
*
Note: the multimap assumes complete ownership over of {@code map} and
* the sets returned by {@code factory}. Those objects should not be manually
* updated and they should not use soft, weak, or phantom references.
*
* @param map place to store the mapping from each key to its corresponding
* values
* @param factory supplier of new, empty sets that will each hold all values
* for a given key
* @throws IllegalArgumentException if {@code map} is not empty
*/
public static SetMultimap newSetMultimap(
Map> map, final Supplier> factory) {
return new CustomSetMultimap<>(map, factory);
}
private static class CustomSetMultimap extends AbstractSetMultimap {
transient Supplier> factory;
CustomSetMultimap(Map> map, Supplier> factory) {
super(map);
this.factory = checkNotNull(factory);
}
@Override
protected Set createCollection() {
return factory.get();
}
/** @serialData the factory and the backing map */
@GwtIncompatible // java.io.ObjectOutputStream
private void writeObject(ObjectOutputStream stream) throws IOException {
stream.defaultWriteObject();
stream.writeObject(factory);
stream.writeObject(backingMap());
}
@GwtIncompatible // java.io.ObjectInputStream
@SuppressWarnings("unchecked") // reading data stored by writeObject
private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
stream.defaultReadObject();
factory = (Supplier>) stream.readObject();
Map> map = (Map>) stream.readObject();
setMap(map);
}
@GwtIncompatible // not needed in emulated source
private static final long serialVersionUID = 0;
}
/**
* Creates a new {@code SortedSetMultimap} that uses the provided map and
* factory. It can generate a multimap based on arbitrary {@link Map} and
* {@link SortedSet} classes.
*
* The {@code factory}-generated and {@code map} classes determine the
* multimap iteration order. They also specify the behavior of the
* {@code equals}, {@code hashCode}, and {@code toString} methods for the
* multimap and its returned views. However, the multimap's {@code get}
* method returns instances of a different class than {@code factory.get()}
* does.
*
*
The multimap is serializable if {@code map}, {@code factory}, the
* sets generated by {@code factory}, and the multimap contents are all
* serializable.
*
*
The multimap is not threadsafe when any concurrent operations update the
* multimap, even if {@code map} and the instances generated by
* {@code factory} are. Concurrent read operations will work correctly. To
* allow concurrent update operations, wrap the multimap with a call to
* {@link #synchronizedSortedSetMultimap}.
*
*
Call this method only when the simpler methods
* {@link TreeMultimap#create()} and
* {@link TreeMultimap#create(Comparator, Comparator)} won't suffice.
*
*
Note: the multimap assumes complete ownership over of {@code map} and
* the sets returned by {@code factory}. Those objects should not be manually
* updated and they should not use soft, weak, or phantom references.
*
* @param map place to store the mapping from each key to its corresponding
* values
* @param factory supplier of new, empty sorted sets that will each hold
* all values for a given key
* @throws IllegalArgumentException if {@code map} is not empty
*/
public static SortedSetMultimap newSortedSetMultimap(
Map> map, final Supplier> factory) {
return new CustomSortedSetMultimap<>(map, factory);
}
private static class CustomSortedSetMultimap extends AbstractSortedSetMultimap {
transient Supplier> factory;
transient Comparator valueComparator;
CustomSortedSetMultimap(Map> map, Supplier> factory) {
super(map);
this.factory = checkNotNull(factory);
valueComparator = factory.get().comparator();
}
@Override
protected SortedSet createCollection() {
return factory.get();
}
@Override
public Comparator valueComparator() {
return valueComparator;
}
/** @serialData the factory and the backing map */
@GwtIncompatible // java.io.ObjectOutputStream
private void writeObject(ObjectOutputStream stream) throws IOException {
stream.defaultWriteObject();
stream.writeObject(factory);
stream.writeObject(backingMap());
}
@GwtIncompatible // java.io.ObjectInputStream
@SuppressWarnings("unchecked") // reading data stored by writeObject
private void readObject(ObjectInputStream stream) throws IOException, ClassNotFoundException {
stream.defaultReadObject();
factory = (Supplier>) stream.readObject();
valueComparator = factory.get().comparator();
Map> map = (Map>) stream.readObject();
setMap(map);
}
@GwtIncompatible // not needed in emulated source
private static final long serialVersionUID = 0;
}
/**
* Copies each key-value mapping in {@code source} into {@code dest}, with
* its key and value reversed.
*
* If {@code source} is an {@link ImmutableMultimap}, consider using
* {@link ImmutableMultimap#inverse} instead.
*
* @param source any multimap
* @param dest the multimap to copy into; usually empty
* @return {@code dest}
*/
@CanIgnoreReturnValue
public static > M invertFrom(
Multimap source, M dest) {
checkNotNull(dest);
for (Map.Entry entry : source.entries()) {
dest.put(entry.getValue(), entry.getKey());
}
return dest;
}
/**
* Returns a synchronized (thread-safe) multimap backed by the specified
* multimap. In order to guarantee serial access, it is critical that
* all access to the backing multimap is accomplished through the
* returned multimap.
*
* It is imperative that the user manually synchronize on the returned
* multimap when accessing any of its collection views:
{@code
*
* Multimap multimap = Multimaps.synchronizedMultimap(
* HashMultimap.create());
* ...
* Collection values = multimap.get(key); // Needn't be in synchronized block
* ...
* synchronized (multimap) { // Synchronizing on multimap, not values!
* Iterator 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 {@link Multimap#removeAll} and
* {@link Multimap#replaceValues} methods return collections that aren't
* synchronized.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param multimap the multimap to be wrapped in a synchronized view
* @return a synchronized view of the specified multimap
*/
public static Multimap synchronizedMultimap(Multimap multimap) {
return Synchronized.multimap(multimap, null);
}
/**
* Returns an unmodifiable view of the specified multimap. 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 {@code UnsupportedOperationException}.
*
* Note that the generated multimap's {@link Multimap#removeAll} and
* {@link Multimap#replaceValues} methods return collections that are
* modifiable.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param delegate the multimap for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified multimap
*/
public static Multimap unmodifiableMultimap(Multimap delegate) {
if (delegate instanceof UnmodifiableMultimap || delegate instanceof ImmutableMultimap) {
return delegate;
}
return new UnmodifiableMultimap<>(delegate);
}
/**
* Simply returns its argument.
*
* @deprecated no need to use this
* @since 10.0
*/
@Deprecated
public static Multimap unmodifiableMultimap(ImmutableMultimap delegate) {
return checkNotNull(delegate);
}
private static class UnmodifiableMultimap extends ForwardingMultimap
implements Serializable {
final Multimap delegate;
transient Collection> entries;
transient Multiset keys;
transient Set keySet;
transient Collection values;
transient Map> map;
UnmodifiableMultimap(final Multimap delegate) {
this.delegate = checkNotNull(delegate);
}
@Override
protected Multimap delegate() {
return delegate;
}
@Override
public void clear() {
throw new UnsupportedOperationException();
}
@Override
public Map> asMap() {
Map> result = map;
if (result == null) {
result =
map =
Collections.unmodifiableMap(
Maps.transformValues(
delegate.asMap(),
new Function, Collection>() {
@Override
public Collection apply(Collection collection) {
return unmodifiableValueCollection(collection);
}
}));
}
return result;
}
@Override
public Collection> entries() {
Collection> result = entries;
if (result == null) {
entries = result = unmodifiableEntries(delegate.entries());
}
return result;
}
@Override
public Collection get(K key) {
return unmodifiableValueCollection(delegate.get(key));
}
@Override
public Multiset keys() {
Multiset result = keys;
if (result == null) {
keys = result = Multisets.unmodifiableMultiset(delegate.keys());
}
return result;
}
@Override
public Set keySet() {
Set result = keySet;
if (result == null) {
keySet = result = Collections.unmodifiableSet(delegate.keySet());
}
return result;
}
@Override
public boolean put(K key, V value) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(Multimap multimap) {
throw new UnsupportedOperationException();
}
@Override
public boolean remove(Object key, Object value) {
throw new UnsupportedOperationException();
}
@Override
public Collection removeAll(Object key) {
throw new UnsupportedOperationException();
}
@Override
public Collection replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public Collection values() {
Collection result = values;
if (result == null) {
values = result = Collections.unmodifiableCollection(delegate.values());
}
return result;
}
private static final long serialVersionUID = 0;
}
private static class UnmodifiableListMultimap extends UnmodifiableMultimap
implements ListMultimap {
UnmodifiableListMultimap(ListMultimap delegate) {
super(delegate);
}
@Override
public ListMultimap delegate() {
return (ListMultimap) super.delegate();
}
@Override
public List get(K key) {
return Collections.unmodifiableList(delegate().get(key));
}
@Override
public List removeAll(Object key) {
throw new UnsupportedOperationException();
}
@Override
public List replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
private static final long serialVersionUID = 0;
}
private static class UnmodifiableSetMultimap extends UnmodifiableMultimap
implements SetMultimap {
UnmodifiableSetMultimap(SetMultimap delegate) {
super(delegate);
}
@Override
public SetMultimap delegate() {
return (SetMultimap) super.delegate();
}
@Override
public Set get(K key) {
/*
* Note that this doesn't return a SortedSet when delegate is a
* SortedSetMultiset, unlike (SortedSet) super.get().
*/
return Collections.unmodifiableSet(delegate().get(key));
}
@Override
public Set> entries() {
return Maps.unmodifiableEntrySet(delegate().entries());
}
@Override
public Set removeAll(Object key) {
throw new UnsupportedOperationException();
}
@Override
public Set replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
private static final long serialVersionUID = 0;
}
private static class UnmodifiableSortedSetMultimap extends UnmodifiableSetMultimap
implements SortedSetMultimap {
UnmodifiableSortedSetMultimap(SortedSetMultimap delegate) {
super(delegate);
}
@Override
public SortedSetMultimap delegate() {
return (SortedSetMultimap) super.delegate();
}
@Override
public SortedSet get(K key) {
return Collections.unmodifiableSortedSet(delegate().get(key));
}
@Override
public SortedSet removeAll(Object key) {
throw new UnsupportedOperationException();
}
@Override
public SortedSet replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public Comparator valueComparator() {
return delegate().valueComparator();
}
private static final long serialVersionUID = 0;
}
/**
* Returns a synchronized (thread-safe) {@code SetMultimap} backed by the
* specified multimap.
*
* You must follow the warnings described in {@link #synchronizedMultimap}.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param multimap the multimap to be wrapped
* @return a synchronized view of the specified multimap
*/
public static SetMultimap synchronizedSetMultimap(SetMultimap multimap) {
return Synchronized.setMultimap(multimap, null);
}
/**
* Returns an unmodifiable view of the specified {@code 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
* {@code UnsupportedOperationException}.
*
* Note that the generated multimap's {@link Multimap#removeAll} and
* {@link Multimap#replaceValues} methods return collections that are
* modifiable.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param delegate the multimap for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified multimap
*/
public static SetMultimap unmodifiableSetMultimap(SetMultimap delegate) {
if (delegate instanceof UnmodifiableSetMultimap || delegate instanceof ImmutableSetMultimap) {
return delegate;
}
return new UnmodifiableSetMultimap<>(delegate);
}
/**
* Simply returns its argument.
*
* @deprecated no need to use this
* @since 10.0
*/
@Deprecated
public static SetMultimap unmodifiableSetMultimap(
ImmutableSetMultimap delegate) {
return checkNotNull(delegate);
}
/**
* Returns a synchronized (thread-safe) {@code SortedSetMultimap} backed by
* the specified multimap.
*
* You must follow the warnings described in {@link #synchronizedMultimap}.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param multimap the multimap to be wrapped
* @return a synchronized view of the specified multimap
*/
public static SortedSetMultimap synchronizedSortedSetMultimap(
SortedSetMultimap multimap) {
return Synchronized.sortedSetMultimap(multimap, null);
}
/**
* Returns an unmodifiable view of the specified {@code 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
* {@code UnsupportedOperationException}.
*
* Note that the generated multimap's {@link Multimap#removeAll} and
* {@link Multimap#replaceValues} methods return collections that are
* modifiable.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param delegate the multimap for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified multimap
*/
public static SortedSetMultimap unmodifiableSortedSetMultimap(
SortedSetMultimap delegate) {
if (delegate instanceof UnmodifiableSortedSetMultimap) {
return delegate;
}
return new UnmodifiableSortedSetMultimap<>(delegate);
}
/**
* Returns a synchronized (thread-safe) {@code ListMultimap} backed by the
* specified multimap.
*
* You must follow the warnings described in {@link #synchronizedMultimap}.
*
* @param multimap the multimap to be wrapped
* @return a synchronized view of the specified multimap
*/
public static ListMultimap synchronizedListMultimap(ListMultimap multimap) {
return Synchronized.listMultimap(multimap, null);
}
/**
* Returns an unmodifiable view of the specified {@code 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
* {@code UnsupportedOperationException}.
*
* Note that the generated multimap's {@link Multimap#removeAll} and
* {@link Multimap#replaceValues} methods return collections that are
* modifiable.
*
*
The returned multimap will be serializable if the specified multimap is
* serializable.
*
* @param delegate the multimap for which an unmodifiable view is to be
* returned
* @return an unmodifiable view of the specified multimap
*/
public static ListMultimap unmodifiableListMultimap(ListMultimap delegate) {
if (delegate instanceof UnmodifiableListMultimap || delegate instanceof ImmutableListMultimap) {
return delegate;
}
return new UnmodifiableListMultimap<>(delegate);
}
/**
* Simply returns its argument.
*
* @deprecated no need to use this
* @since 10.0
*/
@Deprecated
public static ListMultimap unmodifiableListMultimap(
ImmutableListMultimap delegate) {
return checkNotNull(delegate);
}
/**
* Returns an unmodifiable view of the specified collection, preserving the
* interface for instances of {@code SortedSet}, {@code Set}, {@code List} and
* {@code Collection}, in that order of preference.
*
* @param collection the collection for which to return an unmodifiable view
* @return an unmodifiable view of the collection
*/
private static Collection unmodifiableValueCollection(Collection collection) {
if (collection instanceof SortedSet) {
return Collections.unmodifiableSortedSet((SortedSet) collection);
} else if (collection instanceof Set) {
return Collections.unmodifiableSet((Set) collection);
} else if (collection instanceof List) {
return Collections.unmodifiableList((List) collection);
}
return Collections.unmodifiableCollection(collection);
}
/**
* Returns an unmodifiable view of the specified collection of entries. The
* {@link Entry#setValue} operation throws an {@link
* UnsupportedOperationException}. If the specified collection is a {@code
* Set}, the returned collection is also a {@code Set}.
*
* @param entries the entries for which to return an unmodifiable view
* @return an unmodifiable view of the entries
*/
private static Collection> unmodifiableEntries(
Collection> entries) {
if (entries instanceof Set) {
return Maps.unmodifiableEntrySet((Set>) entries);
}
return new Maps.UnmodifiableEntries<>(Collections.unmodifiableCollection(entries));
}
/**
* Returns {@link ListMultimap#asMap multimap.asMap()}, with its type
* corrected from {@code Map>} to {@code Map>}.
*
* @since 15.0
*/
@Beta
@SuppressWarnings("unchecked")
// safe by specification of ListMultimap.asMap()
public static Map> asMap(ListMultimap multimap) {
return (Map>) (Map) multimap.asMap();
}
/**
* Returns {@link SetMultimap#asMap multimap.asMap()}, with its type corrected
* from {@code Map>} to {@code Map>}.
*
* @since 15.0
*/
@Beta
@SuppressWarnings("unchecked")
// safe by specification of SetMultimap.asMap()
public static Map> asMap(SetMultimap multimap) {
return (Map>) (Map) multimap.asMap();
}
/**
* Returns {@link SortedSetMultimap#asMap multimap.asMap()}, with its type
* corrected from {@code Map>} to
* {@code Map>}.
*
* @since 15.0
*/
@Beta
@SuppressWarnings("unchecked")
// safe by specification of SortedSetMultimap.asMap()
public static Map> asMap(SortedSetMultimap multimap) {
return (Map>) (Map) multimap.asMap();
}
/**
* Returns {@link Multimap#asMap multimap.asMap()}. This is provided for
* parity with the other more strongly-typed {@code asMap()} implementations.
*
* @since 15.0
*/
@Beta
public static Map> asMap(Multimap multimap) {
return multimap.asMap();
}
/**
* Returns a multimap view of the specified map. The multimap is backed by the
* map, so changes to the map are reflected in the multimap, and vice versa.
* If the map is modified while an iteration over one of the multimap's
* collection views is in progress (except through the iterator's own {@code
* remove} operation, or through the {@code 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 {@code put}, {@code putAll} or {@code replaceValues}.
*
*
The returned multimap will be serializable if the specified map is
* serializable.
*
* @param map the backing map for the returned multimap view
*/
public static SetMultimap forMap(Map map) {
return new MapMultimap<>(map);
}
/** @see Multimaps#forMap */
private static class MapMultimap extends AbstractMultimap
implements SetMultimap, Serializable {
final Map map;
MapMultimap(Map map) {
this.map = checkNotNull(map);
}
@Override
public int size() {
return map.size();
}
@Override
public boolean containsKey(Object key) {
return map.containsKey(key);
}
@Override
public boolean containsValue(Object value) {
return map.containsValue(value);
}
@Override
public boolean containsEntry(Object key, Object value) {
return map.entrySet().contains(Maps.immutableEntry(key, value));
}
@Override
public Set get(final K key) {
return new Sets.ImprovedAbstractSet() {
@Override
public Iterator iterator() {
return new Iterator() {
int i;
@Override
public boolean hasNext() {
return (i == 0) && map.containsKey(key);
}
@Override
public V next() {
if (!hasNext()) {
throw new NoSuchElementException();
}
i++;
return map.get(key);
}
@Override
public void remove() {
checkRemove(i == 1);
i = -1;
map.remove(key);
}
};
}
@Override
public int size() {
return map.containsKey(key) ? 1 : 0;
}
};
}
@Override
public boolean put(K key, V value) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(Multimap multimap) {
throw new UnsupportedOperationException();
}
@Override
public Set replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public boolean remove(Object key, Object value) {
return map.entrySet().remove(Maps.immutableEntry(key, value));
}
@Override
public Set removeAll(Object key) {
Set values = new HashSet(2);
if (!map.containsKey(key)) {
return values;
}
values.add(map.remove(key));
return values;
}
@Override
public void clear() {
map.clear();
}
@Override
public Set keySet() {
return map.keySet();
}
@Override
public Collection values() {
return map.values();
}
@Override
public Set> entries() {
return map.entrySet();
}
@Override
Iterator> entryIterator() {
return map.entrySet().iterator();
}
@Override
Map> createAsMap() {
return new AsMap<>(this);
}
@Override
public int hashCode() {
return map.hashCode();
}
private static final long serialVersionUID = 7845222491160860175L;
}
/**
* Returns a view of a multimap 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: {@code
*
* Multimap multimap =
* ImmutableSetMultimap.of("a", 2, "b", -3, "b", -3, "a", 4, "c", 6);
* Function square = new Function() {
* public String apply(Integer in) {
* return Integer.toString(in * in);
* }
* };
* Multimap transformed =
* Multimaps.transformValues(multimap, square);
* System.out.println(transformed);}
*
* ... prints {@code {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 {@code equals} and {@code hashCode} methods
* of the returned multimap are meaningless, since there is not a definition
* of {@code equals} or {@code hashCode} for general collections, and
* {@code get()} will return a general {@code Collection} as opposed to a
* {@code List} or a {@code 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
* {@link Multimap#containsValue} and {@code Multimap.toString()}. For this to
* perform well, {@code 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.
*
* @since 7.0
*/
public static Multimap transformValues(
Multimap fromMultimap, final Function function) {
checkNotNull(function);
EntryTransformer transformer = Maps.asEntryTransformer(function);
return transformEntries(fromMultimap, transformer);
}
/**
* Returns a view of a multimap whose values are derived from the original
* multimap's entries. In contrast to {@link #transformValues}, 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:
{@code
*
* SetMultimap multimap =
* ImmutableSetMultimap.of("a", 1, "a", 4, "b", -6);
* EntryTransformer transformer =
* new EntryTransformer() {
* public String transformEntry(String key, Integer value) {
* return (value >= 0) ? key : "no" + key;
* }
* };
* Multimap transformed =
* Multimaps.transformEntries(multimap, transformer);
* System.out.println(transformed);}
*
* ... prints {@code {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 {@code equals} and {@code hashCode} methods
* of the returned multimap are meaningless, since there is not a definition
* of {@code equals} or {@code hashCode} for general collections, and
* {@code get()} will return a general {@code Collection} as opposed to a
* {@code List} or a {@code 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 {@link
* Multimap#containsValue} and {@link Object#toString}. For this to perform
* well, {@code 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 {@code k} of
* {@code EntryTransformer} key type {@code K}, {@code k.equals(k2)} implies
* that {@code k2} is also of type {@code K}. Using an {@code
* EntryTransformer} key type for which this may not hold, such as {@code
* ArrayList}, may risk a {@code ClassCastException} when calling methods on
* the transformed multimap.
*
* @since 7.0
*/
public static Multimap transformEntries(
Multimap fromMap, EntryTransformer transformer) {
return new TransformedEntriesMultimap<>(fromMap, transformer);
}
private static class TransformedEntriesMultimap extends AbstractMultimap {
final Multimap fromMultimap;
final EntryTransformer transformer;
TransformedEntriesMultimap(
Multimap fromMultimap,
final EntryTransformer transformer) {
this.fromMultimap = checkNotNull(fromMultimap);
this.transformer = checkNotNull(transformer);
}
Collection transform(K key, Collection values) {
Function function = Maps.asValueToValueFunction(transformer, key);
if (values instanceof List) {
return Lists.transform((List) values, function);
} else {
return Collections2.transform(values, function);
}
}
@Override
Map> createAsMap() {
return Maps.transformEntries(
fromMultimap.asMap(),
new EntryTransformer, Collection>() {
@Override
public Collection transformEntry(K key, Collection value) {
return transform(key, value);
}
});
}
@Override
public void clear() {
fromMultimap.clear();
}
@Override
public boolean containsKey(Object key) {
return fromMultimap.containsKey(key);
}
@Override
Iterator> entryIterator() {
return Iterators.transform(
fromMultimap.entries().iterator(), Maps.asEntryToEntryFunction(transformer));
}
@Override
public Collection get(final K key) {
return transform(key, fromMultimap.get(key));
}
@Override
public boolean isEmpty() {
return fromMultimap.isEmpty();
}
@Override
public Set keySet() {
return fromMultimap.keySet();
}
@Override
public Multiset keys() {
return fromMultimap.keys();
}
@Override
public boolean put(K key, V2 value) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public boolean putAll(Multimap multimap) {
throw new UnsupportedOperationException();
}
@SuppressWarnings("unchecked")
@Override
public boolean remove(Object key, Object value) {
return get((K) key).remove(value);
}
@SuppressWarnings("unchecked")
@Override
public Collection removeAll(Object key) {
return transform((K) key, fromMultimap.removeAll(key));
}
@Override
public Collection replaceValues(K key, Iterable values) {
throw new UnsupportedOperationException();
}
@Override
public int size() {
return fromMultimap.size();
}
@Override
Collection createValues() {
return Collections2.transform(
fromMultimap.entries(), Maps.asEntryToValueFunction(transformer));
}
}
/**
* Returns a view of a {@code 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: {@code
*
* ListMultimap multimap
* = ImmutableListMultimap.of("a", 4, "a", 16, "b", 9);
* Function sqrt =
* new Function() {
* public Double apply(Integer in) {
* return Math.sqrt((int) in);
* }
* };
* ListMultimap transformed = Multimaps.transformValues(map,
* sqrt);
* System.out.println(transformed);}
*
* ... prints {@code {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
* {@link Multimap#containsValue} and {@code Multimap.toString()}. For this to
* perform well, {@code 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.
*
* @since 7.0
*/
public static ListMultimap transformValues(
ListMultimap fromMultimap, final Function function) {
checkNotNull(function);
EntryTransformer transformer = Maps.asEntryTransformer(function);
return transformEntries(fromMultimap, transformer);
}
/**
* Returns a view of a {@code ListMultimap} whose values are derived from the
* original multimap's entries. In contrast to
* {@link #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:
{@code
*
* Multimap multimap =
* ImmutableMultimap.of("a", 1, "a", 4, "b", 6);
* EntryTransformer transformer =
* new EntryTransformer() {
* public String transformEntry(String key, Integer value) {
* return key + value;
* }
* };
* Multimap transformed =
* Multimaps.transformEntries(multimap, transformer);
* System.out.println(transformed);}
*
* ... prints {@code {"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 {@link
* Multimap#containsValue} and {@link Object#toString}. For this to perform
* well, {@code 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 {@code k} of
* {@code EntryTransformer} key type {@code K}, {@code k.equals(k2)} implies
* that {@code k2} is also of type {@code K}. Using an {@code
* EntryTransformer} key type for which this may not hold, such as {@code
* ArrayList}, may risk a {@code ClassCastException} when calling methods on
* the transformed multimap.
*
* @since 7.0
*/
public static ListMultimap transformEntries(
ListMultimap fromMap, EntryTransformer transformer) {
return new TransformedEntriesListMultimap<>(fromMap, transformer);
}
private static final class TransformedEntriesListMultimap
extends TransformedEntriesMultimap implements ListMultimap {
TransformedEntriesListMultimap(
ListMultimap fromMultimap, EntryTransformer transformer) {
super(fromMultimap, transformer);
}
@Override
List transform(K key, Collection values) {
return Lists.transform((List) values, Maps.asValueToValueFunction(transformer, key));
}
@Override
public List get(K key) {
return transform(key, fromMultimap.get(key));
}
@SuppressWarnings("unchecked")
@Override
public List removeAll(Object key) {
return transform((K) key, fromMultimap.removeAll(key));
}
@Override
public List