Class Multisets
 java.lang.Object

 com.google.common.collect.Multisets

@GwtCompatible public final class Multisets extends Object
Provides static utility methods for creating and working withMultiset
instances.See the Guava User Guide article on
Multisets
. Since:
 2.0
 Author:
 Kevin Bourrillion, Mike Bostock, Louis Wasserman


Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static boolean
containsOccurrences(Multiset<?> superMultiset, Multiset<?> subMultiset)
Returnstrue
ifsubMultiset.count(o) <= superMultiset.count(o)
for allo
.static <E> ImmutableMultiset<E>
copyHighestCountFirst(Multiset<E> multiset)
Returns a copy ofmultiset
as anImmutableMultiset
whose iteration order is highest count first, with ties broken by the iteration order of the original multiset.static <E extends @Nullable Object>
Multiset<E>difference(Multiset<E> multiset1, Multiset<?> multiset2)
Returns an unmodifiable view of the difference of two multisets.static <E extends @Nullable Object>
Multiset<E>filter(Multiset<E> unfiltered, Predicate<? super E> predicate)
Returns a view of the elements ofunfiltered
that satisfy a predicate.static <E extends @Nullable Object>
Multiset.Entry<E>immutableEntry(E e, int n)
Returns an immutable multiset entry with the specified element and count.static <E extends @Nullable Object>
Multiset<E>intersection(Multiset<E> multiset1, Multiset<?> multiset2)
Returns an unmodifiable view of the intersection of two multisets.static boolean
removeOccurrences(Multiset<?> multisetToModify, Multiset<?> occurrencesToRemove)
For each occurrence of an elemente
inoccurrencesToRemove
, removes one occurrence ofe
inmultisetToModify
.static boolean
removeOccurrences(Multiset<?> multisetToModify, Iterable<?> occurrencesToRemove)
For each occurrence of an elemente
inoccurrencesToRemove
, removes one occurrence ofe
inmultisetToModify
.static boolean
retainOccurrences(Multiset<?> multisetToModify, Multiset<?> multisetToRetain)
ModifiesmultisetToModify
so that its count for an elemente
is at mostmultisetToRetain.count(e)
.static <E extends @Nullable Object>
Multiset<E>sum(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)
Returns an unmodifiable view of the sum of two multisets.static <T extends @Nullable Object,E extends @Nullable Object,M extends Multiset<E>>
Collector<T,?,M>toMultiset(Function<? super T,E> elementFunction, ToIntFunction<? super T> countFunction, Supplier<M> multisetSupplier)
Returns aCollector
that accumulates elements into a multiset created via the specifiedSupplier
, whose elements are the result of applyingelementFunction
to the inputs, with counts equal to the result of applyingcountFunction
to the inputs.static <E extends @Nullable Object>
Multiset<E>union(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)
Returns an unmodifiable view of the union of two multisets.static <E> Multiset<E>
unmodifiableMultiset(ImmutableMultiset<E> multiset)
Deprecated.no need to use thisstatic <E extends @Nullable Object>
Multiset<E>unmodifiableMultiset(Multiset<? extends E> multiset)
Returns an unmodifiable view of the specified multiset.static <E extends @Nullable Object>
SortedMultiset<E>unmodifiableSortedMultiset(SortedMultiset<E> sortedMultiset)
Returns an unmodifiable view of the specified sorted multiset.



Method Detail

toMultiset
public static <T extends @Nullable Object,E extends @Nullable Object,M extends Multiset<E>> Collector<T,?,M> toMultiset(Function<? super T,E> elementFunction, ToIntFunction<? super T> countFunction, Supplier<M> multisetSupplier)
Returns aCollector
that accumulates elements into a multiset created via the specifiedSupplier
, whose elements are the result of applyingelementFunction
to the inputs, with counts equal to the result of applyingcountFunction
to the inputs. Elements are added in encounter order.If the mapped elements contain duplicates (according to
Object.equals(java.lang.Object)
), the element will be added more than once, with the count summed over all appearances of the element.Note that
stream.collect(toMultiset(function, e > 1, supplier))
is equivalent tostream.map(function).collect(Collectors.toCollection(supplier))
.To collect to an
ImmutableMultiset
, useImmutableMultiset.toImmutableMultiset()
. Since:
 22.0

unmodifiableMultiset
public static <E extends @Nullable Object> Multiset<E> unmodifiableMultiset(Multiset<? extends E> multiset)
Returns an unmodifiable view of the specified multiset. Query operations on the returned multiset "read through" to the specified multiset, and attempts to modify the returned multiset result in anUnsupportedOperationException
.The returned multiset will be serializable if the specified multiset is serializable.
 Parameters:
multiset
 the multiset for which an unmodifiable view is to be generated Returns:
 an unmodifiable view of the multiset

unmodifiableMultiset
@Deprecated public static <E> Multiset<E> unmodifiableMultiset(ImmutableMultiset<E> multiset)
Deprecated.no need to use thisSimply returns its argument. Since:
 10.0

unmodifiableSortedMultiset
@Beta public static <E extends @Nullable Object> SortedMultiset<E> unmodifiableSortedMultiset(SortedMultiset<E> sortedMultiset)
Returns an unmodifiable view of the specified sorted multiset. Query operations on the returned multiset "read through" to the specified multiset, and attempts to modify the returned multiset result in anUnsupportedOperationException
.The returned multiset will be serializable if the specified multiset is serializable.
 Parameters:
sortedMultiset
 the sorted multiset for which an unmodifiable view is to be generated Returns:
 an unmodifiable view of the multiset
 Since:
 11.0

immutableEntry
public static <E extends @Nullable Object> Multiset.Entry<E> immutableEntry(E e, int n)
Returns an immutable multiset entry with the specified element and count. The entry will be serializable ife
is. Parameters:
e
 the element to be associated with the returned entryn
 the count to be associated with the returned entry Throws:
IllegalArgumentException
 ifn
is negative

filter
@Beta public static <E extends @Nullable Object> Multiset<E> filter(Multiset<E> unfiltered, Predicate<? super E> predicate)
Returns a view of the elements ofunfiltered
that satisfy a predicate. The returned multiset is a live view ofunfiltered
; changes to one affect the other.The resulting multiset's iterators, and those of its
entrySet()
andelementSet()
, do not supportremove()
. However, all other multiset methods supported byunfiltered
are supported by the returned multiset. When given an element that doesn't satisfy the predicate, the multiset'sadd()
andaddAll()
methods throw anIllegalArgumentException
. When methods such asremoveAll()
andclear()
are called on the filtered multiset, only elements that satisfy the filter will be removed from the underlying multiset.The returned multiset isn't threadsafe or serializable, even if
unfiltered
is.Many of the filtered multiset's methods, such as
size()
, iterate across every element in the underlying multiset and determine which elements satisfy the filter. When a live view is not needed, it may be faster to copy the returned multiset and use the copy.Warning:
predicate
must be consistent with equals, as documented atPredicate.apply(T)
. Do not provide a predicate such asPredicates.instanceOf(ArrayList.class)
, which is inconsistent with equals. (SeeIterables.filter(Iterable, Class)
for related functionality.) Since:
 14.0

union
@Beta public static <E extends @Nullable Object> Multiset<E> union(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)
Returns an unmodifiable view of the union of two multisets. In the returned multiset, the count of each element is the maximum of its counts in the two backing multisets. The iteration order of the returned multiset matches that of the element set ofmultiset1
followed by the members of the element set ofmultiset2
that are not contained inmultiset1
, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1
andmultiset2
are based on different equivalence relations (asHashMultiset
andTreeMultiset
are). Since:
 14.0

intersection
public static <E extends @Nullable Object> Multiset<E> intersection(Multiset<E> multiset1, Multiset<?> multiset2)
Returns an unmodifiable view of the intersection of two multisets. In the returned multiset, the count of each element is the minimum of its counts in the two backing multisets, with elements that would have a count of 0 not included. The iteration order of the returned multiset matches that of the element set ofmultiset1
, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1
andmultiset2
are based on different equivalence relations (asHashMultiset
andTreeMultiset
are). Since:
 2.0

sum
@Beta public static <E extends @Nullable Object> Multiset<E> sum(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)
Returns an unmodifiable view of the sum of two multisets. In the returned multiset, the count of each element is the sum of its counts in the two backing multisets. The iteration order of the returned multiset matches that of the element set ofmultiset1
followed by the members of the element set ofmultiset2
that are not contained inmultiset1
, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1
andmultiset2
are based on different equivalence relations (asHashMultiset
andTreeMultiset
are). Since:
 14.0

difference
@Beta public static <E extends @Nullable Object> Multiset<E> difference(Multiset<E> multiset1, Multiset<?> multiset2)
Returns an unmodifiable view of the difference of two multisets. In the returned multiset, the count of each element is the result of the zerotruncated subtraction of its count in the second multiset from its count in the first multiset, with elements that would have a count of 0 not included. The iteration order of the returned multiset matches that of the element set ofmultiset1
, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1
andmultiset2
are based on different equivalence relations (asHashMultiset
andTreeMultiset
are). Since:
 14.0

containsOccurrences
@CanIgnoreReturnValue public static boolean containsOccurrences(Multiset<?> superMultiset, Multiset<?> subMultiset)
Returnstrue
ifsubMultiset.count(o) <= superMultiset.count(o)
for allo
. Since:
 10.0

retainOccurrences
@CanIgnoreReturnValue public static boolean retainOccurrences(Multiset<?> multisetToModify, Multiset<?> multisetToRetain)
ModifiesmultisetToModify
so that its count for an elemente
is at mostmultisetToRetain.count(e)
.To be precise,
multisetToModify.count(e)
is set toMath.min(multisetToModify.count(e), multisetToRetain.count(e))
. This is similar tointersection
(multisetToModify, multisetToRetain)
, but mutatesmultisetToModify
instead of returning a view.In contrast,
multisetToModify.retainAll(multisetToRetain)
keeps all occurrences of elements that appear at all inmultisetToRetain
, and deletes all occurrences of all other elements. Returns:
true
ifmultisetToModify
was changed as a result of this operation Since:
 10.0

removeOccurrences
@CanIgnoreReturnValue public static boolean removeOccurrences(Multiset<?> multisetToModify, Iterable<?> occurrencesToRemove)
For each occurrence of an elemente
inoccurrencesToRemove
, removes one occurrence ofe
inmultisetToModify
.Equivalently, this method modifies
multisetToModify
so thatmultisetToModify.count(e)
is set toMath.max(0, multisetToModify.count(e)  Iterables.frequency(occurrencesToRemove, e))
.This is not the same as
multisetToModify.
removeAll
(occurrencesToRemove)
, which removes all occurrences of elements that appear inoccurrencesToRemove
. However, this operation is equivalent to, albeit sometimes more efficient than, the following:for (E e : occurrencesToRemove) { multisetToModify.remove(e); }
 Returns:
true
ifmultisetToModify
was changed as a result of this operation Since:
 18.0 (present in 10.0 with a requirement that the second parameter be a
Multiset
)

removeOccurrences
@CanIgnoreReturnValue public static boolean removeOccurrences(Multiset<?> multisetToModify, Multiset<?> occurrencesToRemove)
For each occurrence of an elemente
inoccurrencesToRemove
, removes one occurrence ofe
inmultisetToModify
.Equivalently, this method modifies
multisetToModify
so thatmultisetToModify.count(e)
is set toMath.max(0, multisetToModify.count(e)  occurrencesToRemove.count(e))
.This is not the same as
multisetToModify.
removeAll
(occurrencesToRemove)
, which removes all occurrences of elements that appear inoccurrencesToRemove
. However, this operation is equivalent to, albeit sometimes more efficient than, the following:for (E e : occurrencesToRemove) { multisetToModify.remove(e); }
 Returns:
true
ifmultisetToModify
was changed as a result of this operation Since:
 10.0 (missing in 18.0 when only the overload taking an
Iterable
was present)

copyHighestCountFirst
@Beta public static <E> ImmutableMultiset<E> copyHighestCountFirst(Multiset<E> multiset)
Returns a copy ofmultiset
as anImmutableMultiset
whose iteration order is highest count first, with ties broken by the iteration order of the original multiset. Since:
 11.0

