Class 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
    Author:
    Kevin Bourrillion, Mike Bostock, Louis Wasserman
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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 puts the highest count first, with ties broken by the iteration order of the original multiset.
      static <E extends @Nullable java.lang.Object>
      Multiset<E>
      difference​(Multiset<E> multiset1, Multiset<?> multiset2)
      Returns an unmodifiable view of the difference of two multisets.
      static <E extends @Nullable java.lang.Object>
      Multiset<E>
      filter​(Multiset<E> unfiltered, Predicate<? super E> predicate)
      Returns a view of the elements of unfiltered that satisfy a predicate.
      static <E extends @Nullable java.lang.Object>
      Multiset.Entry<E>
      immutableEntry​(E e, int n)
      Returns an immutable multiset entry with the specified element and count.
      static <E extends @Nullable java.lang.Object>
      Multiset<E>
      intersection​(Multiset<E> multiset1, Multiset<?> multiset2)
      Returns an unmodifiable view of the intersection of two multisets.
      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 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 retainOccurrences​(Multiset<?> multisetToModify, Multiset<?> multisetToRetain)
      Modifies multisetToModify so that its count for an element e is at most multisetToRetain.count(e).
      static <E extends @Nullable java.lang.Object>
      Multiset<E>
      sum​(Multiset<? extends E> multiset1, Multiset<? extends E> multiset2)
      Returns an unmodifiable view of the sum of two multisets.
      static <T extends @Nullable java.lang.Object,​E extends @Nullable java.lang.Object,​M extends Multiset<E>>
      java.util.stream.Collector<T,​?,​M>
      toMultiset​(java.util.function.Function<? super T,​E> elementFunction, java.util.function.ToIntFunction<? super T> countFunction, java.util.function.Supplier<M> multisetSupplier)
      Returns a Collector that accumulates elements into a multiset created via the specified Supplier, whose elements are the result of applying elementFunction to the inputs, with counts equal to the result of applying countFunction to the inputs.
      static <E extends @Nullable java.lang.Object>
      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 extends @Nullable java.lang.Object>
      Multiset<E>
      unmodifiableMultiset​(Multiset<? extends E> multiset)
      Returns an unmodifiable view of the specified multiset.
      static <E extends @Nullable java.lang.Object>
      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

      • toMultiset

        @Beta
        public static <T extends @Nullable java.lang.Object,​E extends @Nullable java.lang.Object,​M extends Multiset<E>> java.util.stream.Collector<T,​?,​M> toMultiset​(java.util.function.Function<? super T,​E> elementFunction,
                                                                                                                                                                                             java.util.function.ToIntFunction<? super T> countFunction,
                                                                                                                                                                                             java.util.function.Supplier<M> multisetSupplier)
        Returns a Collector that accumulates elements into a multiset created via the specified Supplier, whose elements are the result of applying elementFunction to the inputs, with counts equal to the result of applying countFunction to the inputs. Elements are added in encounter order.

        If the mapped elements contain duplicates (according to Object.equals(java.lang.Object)), the element will be added more than once, with the count summed over all appearances of the element.

        Note that stream.collect(toMultiset(function, e -> 1, supplier)) is equivalent to stream.map(function).collect(Collectors.toCollection(supplier)).

        To collect to an ImmutableMultiset, use ImmutableMultiset.toImmutableMultiset().

        Since:
        33.2.0 (available since 22.0 in guava-jre)
      • unmodifiableMultiset

        public static <E extends @Nullable java.lang.Object> 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
      • unmodifiableSortedMultiset

        public static <E extends @Nullable java.lang.Object> 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 extends @Nullable java.lang.Object> Multiset.Entry<E> immutableEntry​(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

        public static <E extends @Nullable java.lang.Object> 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

        public static <E extends @Nullable java.lang.Object> 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 extends @Nullable java.lang.Object> 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

        public static <E extends @Nullable java.lang.Object> 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

        public static <E extends @Nullable java.lang.Object> 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
      • retainOccurrences

        @CanIgnoreReturnValue
        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

        @CanIgnoreReturnValue
        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

        @CanIgnoreReturnValue
        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)