com.google.common.collect
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 with Multiset instances.

See the Guava User Guide article on Multisets.

Since:

2.0 (imported from Google Collections Library)

Author:

Kevin Bourrillion, Mike Bostock, Louis Wasserman

Method Summary

static boolean	containsOccurrences(Multiset<?> superMultiset, Multiset<?> subMultiset) Returns true if subMultiset.count(o) <= superMultiset.count(o) for all o.
static <E> ImmutableMultiset<E>	copyHighestCountFirst(Multiset<E> multiset) Returns a copy of multiset as an ImmutableMultiset whose iteration order is highest count first, with ties broken by the iteration order of the original multiset.
static <E> Multiset.Entry<E>	immutableEntry(E e, int n) Returns an immutable multiset entry with the specified element and count.
static <E> 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 element e in occurrencesToRemove, removes one occurrence of e in multisetToModify.
static boolean	retainOccurrences(Multiset<?> multisetToModify, Multiset<?> multisetToRetain) Modifies multisetToModify so that its count for an element e is at most multisetToRetain.count(e).
static <E> Multiset<E>	unmodifiableMultiset(ImmutableMultiset<E> multiset) Deprecated. no need to use this
static <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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

unmodifiableMultiset

public static <E> 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 an UnsupportedOperationException.

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 this

Simply returns its argument.

Since:

10.0

unmodifiableSortedMultiset

@Beta
public static <E> 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 an UnsupportedOperationException.

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> Multiset.Entry<E> immutableEntry(@Nullable
                                                   E e,
                                                   int n)

Returns an immutable multiset entry with the specified element and count. The entry will be serializable if e is.

Parameters:

e - the element to be associated with the returned entry

n - the count to be associated with the returned entry

Throws:

IllegalArgumentException - if n is negative

intersection

public static <E> Multiset<E> intersection(Multiset<E> multiset1,
                                           Multiset<?> multiset2)

Returns an unmodifiable view of the intersection of two multisets. An element's count in the multiset is the smaller of its counts in the two backing multisets. The iteration order of the returned multiset matches the element set of multiset1, with repeated occurrences of the same element appearing consecutively.

Results are undefined if multiset1 and multiset2 are based on different equivalence relations (as HashMultiset and TreeMultiset are).

Since:

2.0

containsOccurrences

public static boolean containsOccurrences(Multiset<?> superMultiset,
                                          Multiset<?> subMultiset)

Returns true if subMultiset.count(o) <= superMultiset.count(o) for all o.

Since:

10.0

retainOccurrences

public static boolean retainOccurrences(Multiset<?> multisetToModify,
                                        Multiset<?> multisetToRetain)

Modifies multisetToModify so that its count for an element e is at most multisetToRetain.count(e).

To be precise, multisetToModify.count(e) is set to Math.min(multisetToModify.count(e), multisetToRetain.count(e)). This is similar to intersection (multisetToModify, multisetToRetain), but mutates multisetToModify instead of returning a view.

In contrast, multisetToModify.retainAll(multisetToRetain) keeps all occurrences of elements that appear at all in multisetToRetain, and deletes all occurrences of all other elements.

Returns:

true if multisetToModify was changed as a result of this operation

Since:

10.0

removeOccurrences

public static boolean removeOccurrences(Multiset<?> multisetToModify,
                                        Multiset<?> occurrencesToRemove)

For each occurrence of an element e in occurrencesToRemove, removes one occurrence of e in multisetToModify.

Equivalently, this method modifies multisetToModify so that multisetToModify.count(e) is set to Math.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 in occurrencesToRemove. However, this operation is equivalent to, albeit more efficient than, the following:

   for (E e : occurrencesToRemove) {
     multisetToModify.remove(e);
   }

Returns:

true if multisetToModify was changed as a result of this operation

Since:

10.0

copyHighestCountFirst

@Beta
public static <E> ImmutableMultiset<E> copyHighestCountFirst(Multiset<E> multiset)

Returns a copy of multiset as an ImmutableMultiset whose iteration order is highest count first, with ties broken by the iteration order of the original multiset.

Since:

11.0