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 Details

  • 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