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 classprivate static final class(package private) static class(package private) static classprivate static final class(package private) static class(package private) static final class(package private) static classprivate static classAnAbstractMultisetwith additional default implementations, some of them linear-time implementations in terms ofelementSetandentrySet. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static <E> booleanaddAllImpl(Multiset<E> self, Multiset<? extends E> elements) A specialization ofaddAllImplfor whenelementsis itself a Multiset.(package private) static <E> booleanaddAllImpl(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 booleancontainsOccurrences(Multiset<?> superMultiset, Multiset<?> subMultiset) ReturnstrueifsubMultiset.count(o) <= superMultiset.count(o)for allo.static <E> ImmutableMultiset<E>copyHighestCountFirst(Multiset<E> multiset) Returns a copy ofmultisetas anImmutableMultisetwhose 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 booleanequalsImpl(Multiset<?> multiset, Object object) An implementation ofMultiset.equals(java.lang.Object).static <E> Multiset<E>Returns a view of the elements ofunfilteredthat 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 intinferDistinctElements(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 intlinearTimeSizeImpl(Multiset<?> multiset) An implementation ofMultiset.size().(package private) static booleanremoveAllImpl(Multiset<?> self, Collection<?> elementsToRemove) An implementation ofMultiset.removeAll(java.util.Collection<?>).static booleanremoveOccurrences(Multiset<?> multisetToModify, Multiset<?> occurrencesToRemove) For each occurrence of an elementeinoccurrencesToRemove, removes one occurrence ofeinmultisetToModify.static booleanremoveOccurrences(Multiset<?> multisetToModify, Iterable<?> occurrencesToRemove) For each occurrence of an elementeinoccurrencesToRemove, removes one occurrence ofeinmultisetToModify.(package private) static booleanretainAllImpl(Multiset<?> self, Collection<?> elementsToRetain) An implementation ofMultiset.retainAll(java.util.Collection<?>).static booleanretainOccurrences(Multiset<?> multisetToModify, Multiset<?> multisetToRetain) ModifiesmultisetToModifyso that its count for an elementeis at mostmultisetToRetain.count(e).private static <E> booleanretainOccurrencesImpl(Multiset<E> multisetToModify, Multiset<?> occurrencesToRetain) Delegate implementation which cares about the element type.(package private) static <E> intsetCountImpl(Multiset<E> self, E element, int count) An implementation ofMultiset.setCount(Object, int).(package private) static <E> booleansetCountImpl(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 aCollectorthat accumulates elements into a multiset created via the specifiedSupplier, whose elements are the result of applyingelementFunctionto the inputs, with counts equal to the result of applyingcountFunctionto 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 aCollectorthat accumulates elements into a multiset created via the specifiedSupplier, whose elements are the result of applyingelementFunctionto the inputs, with counts equal to the result of applyingcountFunctionto 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 ifeis.- Parameters:
e- the element to be associated with the returned entryn- the count to be associated with the returned entry- Throws:
IllegalArgumentException- ifnis negative
-
filter
Returns a view of the elements ofunfilteredthat 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 byunfilteredare 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
unfilteredis.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:
predicatemust 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 ifelementsis 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 ofmultiset1followed by the members of the element set ofmultiset2that are not contained inmultiset1, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1andmultiset2are based on different equivalence relations (asHashMultisetandTreeMultisetare).- 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
multiset1andmultiset2are based on different equivalence relations (asHashMultisetandTreeMultisetare).- 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 ofmultiset1followed by the members of the element set ofmultiset2that are not contained inmultiset1, with repeated occurrences of the same element appearing consecutively.Results are undefined if
multiset1andmultiset2are based on different equivalence relations (asHashMultisetandTreeMultisetare).- 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
multiset1andmultiset2are based on different equivalence relations (asHashMultisetandTreeMultisetare).- Since:
- 14.0
-
containsOccurrences
ReturnstrueifsubMultiset.count(o) <= superMultiset.count(o)for allo.- Since:
- 10.0
-
retainOccurrences
ModifiesmultisetToModifyso that its count for an elementeis 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 mutatesmultisetToModifyinstead 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:
trueifmultisetToModifywas 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 elementeinoccurrencesToRemove, removes one occurrence ofeinmultisetToModify.Equivalently, this method modifies
multisetToModifyso 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:
trueifmultisetToModifywas 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 elementeinoccurrencesToRemove, removes one occurrence ofeinmultisetToModify.Equivalently, this method modifies
multisetToModifyso 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:
trueifmultisetToModifywas changed as a result of this operation- Since:
- 10.0 (missing in 18.0 when only the overload taking an
Iterablewas present)
-
equalsImpl
An implementation ofMultiset.equals(java.lang.Object). -
addAllImpl
An implementation ofCollection.addAll(java.util.Collection<? extends E>). -
addAllImpl
A specialization ofaddAllImplfor whenelementsis 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 ofmultisetas anImmutableMultisetwhose iteration order puts the highest count first, with ties broken by the iteration order of the original multiset.- Since:
- 11.0
-