/*
    * 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
     }
 
 }