Class Multisets
Multiset
instances.
See the Guava User Guide article on
Multisets
.
- Since:
- 2.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static class
private static final class
(package private) static class
(package private) static class
private static final class
(package private) static class
(package private) static final class
(package private) static class
private static class
AnAbstractMultiset
with additional default implementations, some of them linear-time implementations in terms ofelementSet
andentrySet
. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static <E> boolean
addAllImpl
(Multiset<E> self, Multiset<? extends E> elements) A specialization ofaddAllImpl
for whenelements
is itself a Multiset.(package private) static <E> boolean
addAllImpl
(Multiset<E> self, Collection<? extends E> elements) An implementation ofCollection.addAll(java.util.Collection<? extends E>)
.(package private) static <T> Multiset
<T> Used to avoid http://bugs.sun.com/view_bug.do?bug_id=6558557static 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 puts the highest count first, with ties broken by the iteration order of the original multiset.static <E> Multiset
<E> difference
(Multiset<E> multiset1, Multiset<?> multiset2) Returns an unmodifiable view of the difference of two multisets.(package private) static <E> Iterator
<E> elementIterator
(Iterator<Multiset.Entry<E>> entryIterator) (package private) static boolean
equalsImpl
(Multiset<?> multiset, Object object) An implementation ofMultiset.equals(java.lang.Object)
.static <E> Multiset
<E> Returns a view of the elements ofunfiltered
that satisfy a predicate.static <E> Multiset.Entry
<E> immutableEntry
(E e, int n) Returns an immutable multiset entry with the specified element and count.(package private) static int
inferDistinctElements
(Iterable<?> elements) Returns the expected number of distinct elements given the specified elements.static <E> Multiset
<E> intersection
(Multiset<E> multiset1, Multiset<?> multiset2) Returns an unmodifiable view of the intersection of two multisets.(package private) static <E> Iterator
<E> iteratorImpl
(Multiset<E> multiset) An implementation ofMultiset.iterator()
.(package private) static int
linearTimeSizeImpl
(Multiset<?> multiset) An implementation ofMultiset.size()
.(package private) static boolean
removeAllImpl
(Multiset<?> self, Collection<?> elementsToRemove) An implementation ofMultiset.removeAll(java.util.Collection<?>)
.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
.(package private) static boolean
retainAllImpl
(Multiset<?> self, Collection<?> elementsToRetain) An implementation ofMultiset.retainAll(java.util.Collection<?>)
.static boolean
retainOccurrences
(Multiset<?> multisetToModify, Multiset<?> multisetToRetain) ModifiesmultisetToModify
so that its count for an elemente
is at mostmultisetToRetain.count(e)
.private static <E> boolean
retainOccurrencesImpl
(Multiset<E> multisetToModify, Multiset<?> occurrencesToRetain) Delegate implementation which cares about the element type.(package private) static <E> int
setCountImpl
(Multiset<E> self, E element, int count) An implementation ofMultiset.setCount(Object, int)
.(package private) static <E> boolean
setCountImpl
(Multiset<E> self, E element, int oldCount, int newCount) An implementation ofMultiset.setCount(Object, int, int)
.(package private) static <E> Spliterator
<E> spliteratorImpl
(Multiset<E> multiset) static <E> Multiset
<E> Returns an unmodifiable view of the sum of two multisets.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> Multiset
<E> 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> Multiset
<E> unmodifiableMultiset
(Multiset<? extends E> multiset) Returns an unmodifiable view of the specified multiset.static <E> SortedMultiset
<E> unmodifiableSortedMultiset
(SortedMultiset<E> sortedMultiset) Returns an unmodifiable view of the specified sorted multiset.
-
Constructor Details
-
Multisets
private Multisets()
-
-
Method Details
-
toMultiset
public static <T,E, Collector<T,M extends Multiset<E>> ?, toMultisetM> (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
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.no need to use thisSimply returns its argument.- Since:
- 10.0
-
unmodifiableSortedMultiset
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
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
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
-
inferDistinctElements
Returns the expected number of distinct elements given the specified elements. The number of distinct elements is only computed ifelements
is an instance ofMultiset
; otherwise the default value of 11 is returned. -
union
public static <E> 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
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
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
Returns an unmodifiable view of the difference of two multisets. In the returned multiset, the count of each element is the result of the zero-truncated 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
Returnstrue
ifsubMultiset.count(o) <= superMultiset.count(o)
for allo
.- Since:
- 10.0
-
retainOccurrences
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
-
retainOccurrencesImpl
private static <E> boolean retainOccurrencesImpl(Multiset<E> multisetToModify, Multiset<?> occurrencesToRetain) Delegate implementation which cares about the element type. -
removeOccurrences
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
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)
-
equalsImpl
An implementation ofMultiset.equals(java.lang.Object)
. -
addAllImpl
An implementation ofCollection.addAll(java.util.Collection<? extends E>)
. -
addAllImpl
A specialization ofaddAllImpl
for whenelements
is itself a Multiset. -
removeAllImpl
An implementation ofMultiset.removeAll(java.util.Collection<?>)
. -
retainAllImpl
An implementation ofMultiset.retainAll(java.util.Collection<?>)
. -
setCountImpl
An implementation ofMultiset.setCount(Object, int)
. -
setCountImpl
An implementation ofMultiset.setCount(Object, int, int)
. -
elementIterator
-
iteratorImpl
An implementation ofMultiset.iterator()
. -
spliteratorImpl
-
linearTimeSizeImpl
An implementation ofMultiset.size()
. -
cast
Used to avoid http://bugs.sun.com/view_bug.do?bug_id=6558557 -
copyHighestCountFirst
Returns a copy ofmultiset
as anImmutableMultiset
whose iteration order puts the highest count first, with ties broken by the iteration order of the original multiset.- Since:
- 11.0
-