Multisets
Date: 2016-05-24

com.google.common.collect

## Class Multisets

- java.lang.Object
- - com.google.common.collect.Multisets

-     @GwtCompatible
      public final class Multisets
      extends java.lang.Object

  Provides static utility methods for creating and working with `Multiset` instances.

  See the Guava User Guide article on `Multisets`.

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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<E>` | `difference(Multiset<E> multiset1, Multiset<?> multiset2)` Returns an unmodifiable view of the difference of two multisets.
    `static <E> Multiset<E>` | `filter(Multiset<E> unfiltered, Predicate<? super E> predicate)` Returns a view of the elements of `unfiltered` 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.
    `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, java.lang.Iterable<?> occurrencesToRemove)` For each occurrence of an element `e` in `occurrencesToRemove`, removes one occurrence of `e` in `multisetToModify`.
    `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>` | `sum(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)` Returns an unmodifiable view of the sum of two multisets.
    `static <E> 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 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:
        `java.lang.IllegalArgumentException` - if `n` is negative

    - #### filter

          @Beta
          @CheckReturnValue
          public static <E> Multiset<E> filter(Multiset<E> unfiltered,
                                                     Predicate<? super E> predicate)

      Returns a view of the elements of `unfiltered` that satisfy a predicate. The returned multiset is a live view of `unfiltered`; changes to one affect the other.

      The resulting multiset's iterators, and those of its `entrySet()` and `elementSet()`, do not support `remove()`. However, all other multiset methods supported by `unfiltered` are supported by the returned multiset. When given an element that doesn't satisfy the predicate, the multiset's `add()` and `addAll()` methods throw an `IllegalArgumentException`. When methods such as `removeAll()` and `clear()` 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 at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals. (See `Iterables.filter(Iterable, Class)` for related functionality.)

      Since:
        14.0

    - #### union

          @Beta
          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 of `multiset1` followed by the members of the element set of `multiset2` that are not contained in `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:
        14.0

    - #### intersection

          public static <E> 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 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

    - #### sum

          @Beta
          public static <E> 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 of `multiset1` followed by the members of the element set of `multiset2` that are not contained in `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:
        14.0

    - #### difference

          @Beta
          public static <E> 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 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 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:
        14.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,
                                  java.lang.Iterable<?> 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) - Iterables.frequency(occurrencesToRemove, 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 sometimes 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:
        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 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 sometimes 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 (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 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