Package org.apache.commons.collections4

# Class MultiSetUtils

java.lang.Object
org.apache.commons.collections4.MultiSetUtils

public class MultiSetUtils extends Object
Provides utility methods and decorators for `MultiSet` and `SortedMultiSet` instances.

Since:
  4.1

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final MultiSet`
  `EMPTY_MULTISET`
  An empty unmodifiable multiset.
  `static final SortedMultiSet`
  `EMPTY_SORTED_MULTISET`
  An empty unmodifiable sorted multiset.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `containsOccurrences(MultiSet<?> superMultiSet, MultiSet<?> subMultiSet)`
  Returns `true` if `superMultiSet` contains at least as many occurrences of each element as `subMultiSet` does; in other words, whether `subMultiSet` is a sub-multiset of `superMultiSet`.
  `static <E> MultiSet<E>`
  `emptyMultiSet()`
  Gets an empty `MultiSet`.
  `static <E> SortedMultiSet<E>`
  `emptySortedMultiSet()`
  Gets an empty `SortedMultiSet`.
  `static <E> MultiSet<E>`
  `predicatedMultiSet(MultiSet<E> multiset, Predicate<? super E> predicate)`
  Returns a predicated (validating) multiset backed by the given multiset.
  `static <E> SortedMultiSet<E>`
  `predicatedSortedMultiSet(SortedMultiSet<E> multiset, Predicate<? super E> predicate)`
  Returns a predicated (validating) sorted multiset backed by the given sorted multiset.
  `static boolean`
  `removeOccurrences(MultiSet<?> multiSetToModify, MultiSet<?> occurrencesToRemove)`
  For each occurrence of an element in `occurrencesToRemove`, removes one occurrence of that element from `multiSetToModify`, if present.
  `static <E> boolean`
  `retainOccurrences(MultiSet<E> multiSetToModify, MultiSet<?> occurrencesToRetain)`
  Modifies `multiSetToModify` so that no element has more occurrences than it has in `occurrencesToRetain`.
  `static <E> MultiSet<E>`
  `synchronizedMultiSet(MultiSet<E> multiset)`
  Returns a synchronized (thread-safe) multiset backed by the given multiset.
  `static <E> SortedMultiSet<E>`
  `synchronizedSortedMultiSet(SortedMultiSet<E> multiset)`
  Returns a synchronized (thread-safe) sorted multiset backed by the given sorted multiset.
  `static <E> MultiSet<E>`
  `transformingMultiSet(MultiSet<E> multiset, Transformer<? super E,? extends E> transformer)`
  Returns a transformed multiset backed by the given multiset.
  `static <E> SortedMultiSet<E>`
  `transformingSortedMultiSet(SortedMultiSet<E> multiset, Transformer<? super E,? extends E> transformer)`
  Returns a transformed sorted multiset backed by the given multiset.
  `static <E> MultiSet<E>`
  `unmodifiableMultiSet(MultiSet<? extends E> multiset)`
  Returns an unmodifiable view of the given multiset.
  `static <E> SortedMultiSet<E>`
  `unmodifiableSortedMultiSet(SortedMultiSet<? extends E> multiset)`
  Returns an unmodifiable view of the given sorted multiset.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### EMPTY_MULTISET

    public static final MultiSet EMPTY_MULTISET
    An empty unmodifiable multiset.

  - ### EMPTY_SORTED_MULTISET

    public static final SortedMultiSet EMPTY_SORTED_MULTISET
    An empty unmodifiable sorted multiset.
    Since:
      4.6.0

- ## Method Details

  - ### containsOccurrences

    public static boolean containsOccurrences(MultiSet<?> superMultiSet, MultiSet<?> subMultiSet)
    Returns `true` if `superMultiSet` contains at least as many occurrences of each element as `subMultiSet` does; in other words, whether `subMultiSet` is a sub-multiset of `superMultiSet`.

    This method provides the cardinality-respecting behavior of `Bag.containsAll(java.util.Collection)` under an explicitly named method. To compare against a plain collection, wrap it first, for example `containsOccurrences(multiSet, new HashMultiSet<>(coll))`.

    Parameters:
      `superMultiSet` - The multiset to check against, must not be null
      `subMultiSet` - The multiset whose occurrences must all be present, must not be null
    Returns:
      `true` if `superMultiSet` contains all occurrences in `subMultiSet`
    Throws:
      `NullPointerException` - if either MultiSet is null
    Since:
      4.6.0

  - ### emptyMultiSet

    public static <E> MultiSet<E> emptyMultiSet()
    Gets an empty `MultiSet`.
    Type Parameters:
      `E` - The element type
    Returns:
      An empty MultiSet

  - ### emptySortedMultiSet

    public static <E> SortedMultiSet<E> emptySortedMultiSet()
    Gets an empty `SortedMultiSet`.
    Type Parameters:
      `E` - The element type
    Returns:
      An empty SortedMultiSet
    Since:
      4.6.0

  - ### predicatedMultiSet

    public static <E> MultiSet<E> predicatedMultiSet(MultiSet<E> multiset, Predicate<? super E> predicate)
    Returns a predicated (validating) multiset backed by the given multiset.

    Only objects that pass the test in the given predicate can be added to the multiset. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original multiset after invoking this method, as it is a backdoor for adding invalid objects.

    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The multiset to predicate, must not be null
      `predicate` - The predicate for the multiset, must not be null
    Returns:
      A predicated multiset backed by the given multiset
    Throws:
      `NullPointerException` - if the MultiSet or Predicate is null

  - ### predicatedSortedMultiSet

    public static <E> SortedMultiSet<E> predicatedSortedMultiSet(SortedMultiSet<E> multiset, Predicate<? super E> predicate)
    Returns a predicated (validating) sorted multiset backed by the given sorted multiset.

    Only objects that pass the test in the given predicate can be added to the multiset. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original multiset after invoking this method, as it is a backdoor for adding invalid objects.

    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The sorted multiset to predicate, must not be null
      `predicate` - The predicate for the multiset, must not be null
    Returns:
      A predicated sorted multiset backed by the given sorted multiset
    Throws:
      `NullPointerException` - if the SortedMultiSet or Predicate is null
    Since:
      4.6.0

  - ### removeOccurrences

    public static boolean removeOccurrences(MultiSet<?> multiSetToModify, MultiSet<?> occurrencesToRemove)
    For each occurrence of an element in `occurrencesToRemove`, removes one occurrence of that element from `multiSetToModify`, if present. That is, if `occurrencesToRemove` contains `n` occurrences of an element, `multiSetToModify` will have `n` fewer occurrences, assuming it had at least `n` to begin with.

    This method provides the cardinality-respecting behavior of `Bag.removeAll(java.util.Collection)` under an explicitly named method. To remove the occurrences of a plain collection, wrap it first, for example `removeOccurrences(multiSet, new HashMultiSet<>(coll))`.

    Parameters:
      `multiSetToModify` - The multiset to remove occurrences from, must not be null
      `occurrencesToRemove` - The occurrences to remove, must not be null
    Returns:
      `true` if `multiSetToModify` was changed as a result of this operation
    Throws:
      `NullPointerException` - if either MultiSet is null
    Since:
      4.6.0

  - ### retainOccurrences

    public static <E> boolean retainOccurrences(MultiSet<E> multiSetToModify, MultiSet<?> occurrencesToRetain)
    Modifies `multiSetToModify` so that no element has more occurrences than it has in `occurrencesToRetain`. That is, if `occurrencesToRetain` contains `n` occurrences of an element and `multiSetToModify` has `m > n` occurrences, `m - n` occurrences are removed; elements not contained in `occurrencesToRetain` are removed entirely.

    This method provides the cardinality-respecting behavior of `Bag.retainAll(java.util.Collection)` under an explicitly named method. To retain the occurrences of a plain collection, wrap it first, for example `retainOccurrences(multiSet, new HashMultiSet<>(coll))`.

    Type Parameters:
      `E` - The element type
    Parameters:
      `multiSetToModify` - The multiset to limit occurrences in, must not be null
      `occurrencesToRetain` - The occurrences to retain, must not be null
    Returns:
      `true` if `multiSetToModify` was changed as a result of this operation
    Throws:
      `NullPointerException` - if either MultiSet is null
    Since:
      4.6.0

  - ### synchronizedMultiSet

    public static <E> MultiSet<E> synchronizedMultiSet(MultiSet<E> multiset)
    Returns a synchronized (thread-safe) multiset backed by the given multiset. In order to guarantee serial access, it is critical that all access to the backing multiset is accomplished through the returned multiset.

    It is imperative that the user manually synchronize on the returned multiset when iterating over it:

         MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
         ...
         synchronized(multiset) {
             Iterator i = multiset.iterator(); // Must be in synchronized block
             while (i.hasNext())
                 foo(i.next());
             }
         }

    Failure to follow this advice may result in non-deterministic behavior.
    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The multiset to synchronize, must not be null
    Returns:
      A synchronized multiset backed by that multiset
    Throws:
      `NullPointerException` - if the MultiSet is null

  - ### synchronizedSortedMultiSet

    public static <E> SortedMultiSet<E> synchronizedSortedMultiSet(SortedMultiSet<E> multiset)
    Returns a synchronized (thread-safe) sorted multiset backed by the given sorted multiset. In order to guarantee serial access, it is critical that all access to the backing multiset is accomplished through the returned multiset.

    It is imperative that the user manually synchronize on the returned multiset when iterating over it:

         SortedMultiSet multiset = MultiSetUtils.synchronizedSortedMultiSet(new TreeMultiSet());
         ...
         synchronized(multiset) {
             Iterator i = multiset.iterator(); // Must be in synchronized block
             while (i.hasNext())
                 foo(i.next());
             }
         }

    Failure to follow this advice may result in non-deterministic behavior.
    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The sorted multiset to synchronize, must not be null
    Returns:
      A synchronized sorted multiset backed by that multiset
    Throws:
      `NullPointerException` - if the SortedMultiSet is null
    Since:
      4.6.0

  - ### transformingMultiSet

    public static <E> MultiSet<E> transformingMultiSet(MultiSet<E> multiset, Transformer<? super E,? extends E> transformer)
    Returns a transformed multiset backed by the given multiset.

    Each object is passed through the transformer as it is added to the MultiSet. It is important not to use the original multiset after invoking this method, as it is a backdoor for adding untransformed objects.

    Existing entries in the specified multiset will not be transformed. If you want that behavior, see `TransformedMultiSet.transformedMultiSet(MultiSet, Transformer)`.

    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The multiset to transform, must not be null
      `transformer` - The transformer for the multiset, must not be null
    Returns:
      A transformed multiset backed by the given multiset
    Throws:
      `NullPointerException` - if the MultiSet or Transformer is null
    Since:
      4.6.0

  - ### transformingSortedMultiSet

    public static <E> SortedMultiSet<E> transformingSortedMultiSet(SortedMultiSet<E> multiset, Transformer<? super E,? extends E> transformer)
    Returns a transformed sorted multiset backed by the given multiset.

    Each object is passed through the transformer as it is added to the MultiSet. It is important not to use the original multiset after invoking this method, as it is a backdoor for adding untransformed objects.

    Existing entries in the specified multiset will not be transformed. If you want that behavior, see `TransformedSortedMultiSet.transformedSortedMultiSet(SortedMultiSet, Transformer)`.

    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The sorted multiset to transform, must not be null
      `transformer` - The transformer for the multiset, must not be null
    Returns:
      A transformed sorted multiset backed by the given multiset
    Throws:
      `NullPointerException` - if the SortedMultiSet or Transformer is null
    Since:
      4.6.0

  - ### unmodifiableMultiSet

    public static <E> MultiSet<E> unmodifiableMultiSet(MultiSet<? extends E> multiset)
    Returns an unmodifiable view of the given multiset. Any modification attempts to the returned multiset will raise an `UnsupportedOperationException`.
    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The multiset whose unmodifiable view is to be returned, must not be null
    Returns:
      An unmodifiable view of that multiset
    Throws:
      `NullPointerException` - if the MultiSet is null

  - ### unmodifiableSortedMultiSet

    public static <E> SortedMultiSet<E> unmodifiableSortedMultiSet(SortedMultiSet<? extends E> multiset)
    Returns an unmodifiable view of the given sorted multiset. Any modification attempts to the returned multiset will raise an `UnsupportedOperationException`.
    Type Parameters:
      `E` - The element type
    Parameters:
      `multiset` - The sorted multiset whose unmodifiable view is to be returned, must not be null
    Returns:
      An unmodifiable view of that sorted multiset
    Throws:
      `NullPointerException` - if the SortedMultiSet is null
    Since:
      4.6.0