MultiSetUtils.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.collections4;
import java.util.ArrayList;
import java.util.Objects;
import org.apache.commons.collections4.multiset.HashMultiSet;
import org.apache.commons.collections4.multiset.PredicatedMultiSet;
import org.apache.commons.collections4.multiset.PredicatedSortedMultiSet;
import org.apache.commons.collections4.multiset.SynchronizedMultiSet;
import org.apache.commons.collections4.multiset.SynchronizedSortedMultiSet;
import org.apache.commons.collections4.multiset.TransformedMultiSet;
import org.apache.commons.collections4.multiset.TransformedSortedMultiSet;
import org.apache.commons.collections4.multiset.TreeMultiSet;
import org.apache.commons.collections4.multiset.UnmodifiableMultiSet;
import org.apache.commons.collections4.multiset.UnmodifiableSortedMultiSet;
/**
* Provides utility methods and decorators for {@link MultiSet} and
* {@link SortedMultiSet} instances.
*
* @since 4.1
*/
public class MultiSetUtils {
/**
* An empty unmodifiable multiset.
*/
@SuppressWarnings("rawtypes") // OK, empty multiset is compatible with any type
public static final MultiSet EMPTY_MULTISET =
UnmodifiableMultiSet.unmodifiableMultiSet(new HashMultiSet<>());
/**
* An empty unmodifiable sorted multiset.
*
* @since 4.6.0
*/
@SuppressWarnings("rawtypes") // OK, empty multiset is compatible with any type
public static final SortedMultiSet EMPTY_SORTED_MULTISET =
UnmodifiableSortedMultiSet.unmodifiableSortedMultiSet(new TreeMultiSet<>());
/**
* Returns {@code true} if {@code superMultiSet} contains at least as many
* occurrences of each element as {@code subMultiSet} does; in other words,
* whether {@code subMultiSet} is a sub-multiset of {@code superMultiSet}.
* <p>
* This method provides the cardinality-respecting behavior of
* {@link Bag#containsAll(java.util.Collection)} under an explicitly named
* method. To compare against a plain collection, wrap it first, for example
* {@code containsOccurrences(multiSet, new HashMultiSet<>(coll))}.
* </p>
*
* @param superMultiSet The multiset to check against, must not be null
* @param subMultiSet The multiset whose occurrences must all be present, must not be null
* @return {@code true} if {@code superMultiSet} contains all occurrences in {@code subMultiSet}
* @throws NullPointerException if either MultiSet is null
* @since 4.6.0
*/
public static boolean containsOccurrences(final MultiSet<?> superMultiSet, final MultiSet<?> subMultiSet) {
Objects.requireNonNull(superMultiSet, "superMultiSet");
Objects.requireNonNull(subMultiSet, "subMultiSet");
for (final MultiSet.Entry<?> entry : subMultiSet.entrySet()) {
if (superMultiSet.getCount(entry.getElement()) < entry.getCount()) {
return false;
}
}
return true;
}
/**
* Gets an empty {@code MultiSet}.
*
* @param <E> The element type
* @return An empty MultiSet
*/
@SuppressWarnings("unchecked") // OK, empty multiset is compatible with any type
public static <E> MultiSet<E> emptyMultiSet() {
return EMPTY_MULTISET;
}
/**
* Gets an empty {@code SortedMultiSet}.
*
* @param <E> The element type
* @return An empty SortedMultiSet
* @since 4.6.0
*/
@SuppressWarnings("unchecked") // OK, empty multiset is compatible with any type
public static <E> SortedMultiSet<E> emptySortedMultiSet() {
return EMPTY_SORTED_MULTISET;
}
/**
* Returns a predicated (validating) multiset backed by the given multiset.
* <p>
* 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.
* </p>
*
* @param <E> The element type
* @param multiset The multiset to predicate, must not be null
* @param predicate The predicate for the multiset, must not be null
* @return A predicated multiset backed by the given multiset
* @throws NullPointerException if the MultiSet or Predicate is null
*/
public static <E> MultiSet<E> predicatedMultiSet(final MultiSet<E> multiset,
final Predicate<? super E> predicate) {
return PredicatedMultiSet.predicatedMultiSet(multiset, predicate);
}
/**
* Returns a predicated (validating) sorted multiset backed by the given sorted
* multiset.
* <p>
* 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.
* </p>
*
* @param <E> The element type
* @param multiset The sorted multiset to predicate, must not be null
* @param predicate The predicate for the multiset, must not be null
* @return A predicated sorted multiset backed by the given sorted multiset
* @throws NullPointerException if the SortedMultiSet or Predicate is null
* @since 4.6.0
*/
public static <E> SortedMultiSet<E> predicatedSortedMultiSet(final SortedMultiSet<E> multiset,
final Predicate<? super E> predicate) {
return PredicatedSortedMultiSet.predicatedSortedMultiSet(multiset, predicate);
}
/**
* For each occurrence of an element in {@code occurrencesToRemove}, removes
* one occurrence of that element from {@code multiSetToModify}, if present.
* That is, if {@code occurrencesToRemove} contains {@code n} occurrences of
* an element, {@code multiSetToModify} will have {@code n} fewer occurrences,
* assuming it had at least {@code n} to begin with.
* <p>
* This method provides the cardinality-respecting behavior of
* {@link Bag#removeAll(java.util.Collection)} under an explicitly named
* method. To remove the occurrences of a plain collection, wrap it first,
* for example {@code removeOccurrences(multiSet, new HashMultiSet<>(coll))}.
* </p>
*
* @param multiSetToModify The multiset to remove occurrences from, must not be null
* @param occurrencesToRemove The occurrences to remove, must not be null
* @return {@code true} if {@code multiSetToModify} was changed as a result of this operation
* @throws NullPointerException if either MultiSet is null
* @since 4.6.0
*/
public static boolean removeOccurrences(final MultiSet<?> multiSetToModify, final MultiSet<?> occurrencesToRemove) {
Objects.requireNonNull(multiSetToModify, "multiSetToModify");
Objects.requireNonNull(occurrencesToRemove, "occurrencesToRemove");
if (multiSetToModify == occurrencesToRemove) {
final boolean changed = !multiSetToModify.isEmpty();
multiSetToModify.clear();
return changed;
}
boolean changed = false;
// snapshot the entries to avoid ConcurrentModificationException when
// occurrencesToRemove is a view backed by multiSetToModify
for (final MultiSet.Entry<?> entry : new ArrayList<>(occurrencesToRemove.entrySet())) {
if (multiSetToModify.remove(entry.getElement(), entry.getCount()) > 0) {
changed = true;
}
}
return changed;
}
/**
* Modifies {@code multiSetToModify} so that no element has more occurrences
* than it has in {@code occurrencesToRetain}. That is, if
* {@code occurrencesToRetain} contains {@code n} occurrences of an element
* and {@code multiSetToModify} has {@code m > n} occurrences, {@code m - n}
* occurrences are removed; elements not contained in
* {@code occurrencesToRetain} are removed entirely.
* <p>
* This method provides the cardinality-respecting behavior of
* {@link Bag#retainAll(java.util.Collection)} under an explicitly named
* method. To retain the occurrences of a plain collection, wrap it first,
* for example {@code retainOccurrences(multiSet, new HashMultiSet<>(coll))}.
* </p>
*
* @param <E> The element type
* @param multiSetToModify The multiset to limit occurrences in, must not be null
* @param occurrencesToRetain The occurrences to retain, must not be null
* @return {@code true} if {@code multiSetToModify} was changed as a result of this operation
* @throws NullPointerException if either MultiSet is null
* @since 4.6.0
*/
public static <E> boolean retainOccurrences(final MultiSet<E> multiSetToModify, final MultiSet<?> occurrencesToRetain) {
Objects.requireNonNull(multiSetToModify, "multiSetToModify");
Objects.requireNonNull(occurrencesToRetain, "occurrencesToRetain");
boolean changed = false;
for (final E element : new ArrayList<>(multiSetToModify.uniqueSet())) {
final int retainCount = occurrencesToRetain.getCount(element);
if (multiSetToModify.getCount(element) > retainCount) {
multiSetToModify.setCount(element, retainCount);
changed = true;
}
}
return changed;
}
/**
* 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.
* <p>
* It is imperative that the user manually synchronize on the returned multiset
* when iterating over it:
* </p>
* <pre>
* MultiSet multiset = MultiSetUtils.synchronizedMultiSet(new HashMultiSet());
* ...
* synchronized(multiset) {
* Iterator i = multiset.iterator(); // Must be in synchronized block
* while (i.hasNext())
* foo(i.next());
* }
* }
* </pre>
*
* Failure to follow this advice may result in non-deterministic behavior.
*
* @param <E> The element type
* @param multiset The multiset to synchronize, must not be null
* @return A synchronized multiset backed by that multiset
* @throws NullPointerException if the MultiSet is null
*/
public static <E> MultiSet<E> synchronizedMultiSet(final MultiSet<E> multiset) {
return SynchronizedMultiSet.synchronizedMultiSet(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.
* <p>
* It is imperative that the user manually synchronize on the returned multiset
* when iterating over it:
* </p>
* <pre>
* SortedMultiSet multiset = MultiSetUtils.synchronizedSortedMultiSet(new TreeMultiSet());
* ...
* synchronized(multiset) {
* Iterator i = multiset.iterator(); // Must be in synchronized block
* while (i.hasNext())
* foo(i.next());
* }
* }
* </pre>
*
* Failure to follow this advice may result in non-deterministic behavior.
*
* @param <E> The element type
* @param multiset The sorted multiset to synchronize, must not be null
* @return A synchronized sorted multiset backed by that multiset
* @throws NullPointerException if the SortedMultiSet is null
* @since 4.6.0
*/
public static <E> SortedMultiSet<E> synchronizedSortedMultiSet(final SortedMultiSet<E> multiset) {
return SynchronizedSortedMultiSet.synchronizedSortedMultiSet(multiset);
}
/**
* Returns a transformed multiset backed by the given multiset.
* <p>
* 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.
* </p>
* <p>
* Existing entries in the specified multiset will not be transformed.
* If you want that behavior, see
* {@link TransformedMultiSet#transformedMultiSet(MultiSet, Transformer)}.
* </p>
*
* @param <E> The element type
* @param multiset The multiset to transform, must not be null
* @param transformer The transformer for the multiset, must not be null
* @return A transformed multiset backed by the given multiset
* @throws NullPointerException if the MultiSet or Transformer is null
* @since 4.6.0
*/
public static <E> MultiSet<E> transformingMultiSet(final MultiSet<E> multiset,
final Transformer<? super E, ? extends E> transformer) {
return TransformedMultiSet.transformingMultiSet(multiset, transformer);
}
/**
* Returns a transformed sorted multiset backed by the given multiset.
* <p>
* 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.
* </p>
* <p>
* Existing entries in the specified multiset will not be transformed.
* If you want that behavior, see
* {@link TransformedSortedMultiSet#transformedSortedMultiSet(SortedMultiSet, Transformer)}.
* </p>
*
* @param <E> The element type
* @param multiset The sorted multiset to transform, must not be null
* @param transformer The transformer for the multiset, must not be null
* @return A transformed sorted multiset backed by the given multiset
* @throws NullPointerException if the SortedMultiSet or Transformer is null
* @since 4.6.0
*/
public static <E> SortedMultiSet<E> transformingSortedMultiSet(final SortedMultiSet<E> multiset,
final Transformer<? super E, ? extends E> transformer) {
return TransformedSortedMultiSet.transformingSortedMultiSet(multiset, transformer);
}
/**
* Returns an unmodifiable view of the given multiset. Any modification attempts
* to the returned multiset will raise an {@link UnsupportedOperationException}.
*
* @param <E> The element type
* @param multiset The multiset whose unmodifiable view is to be returned, must not be null
* @return An unmodifiable view of that multiset
* @throws NullPointerException if the MultiSet is null
*/
public static <E> MultiSet<E> unmodifiableMultiSet(final MultiSet<? extends E> multiset) {
return UnmodifiableMultiSet.unmodifiableMultiSet(multiset);
}
/**
* Returns an unmodifiable view of the given sorted multiset. Any modification
* attempts to the returned multiset will raise an
* {@link UnsupportedOperationException}.
*
* @param <E> The element type
* @param multiset The sorted multiset whose unmodifiable view is to be returned, must not be null
* @return An unmodifiable view of that sorted multiset
* @throws NullPointerException if the SortedMultiSet is null
* @since 4.6.0
*/
public static <E> SortedMultiSet<E> unmodifiableSortedMultiSet(final SortedMultiSet<? extends E> multiset) {
return UnmodifiableSortedMultiSet.unmodifiableSortedMultiSet(multiset);
}
/**
* Don't allow instances.
*/
private MultiSetUtils() {
// empty
}
}