com.google.common.collect
Class Multisets

java.lang.Object
  com.google.common.collect.Multisets

public final class Multisets
extends Object

Provides static utility methods for creating and working with Multiset instances.

Author:

Kevin Bourrillion, Mike Bostock

Method Summary

static <E> Multiset<E>	emptyMultiset() Returns the empty multiset (immutable).
static <E> Multiset<E>	forSet(Set<E> set) Returns a multiset view of the specified set.
static <T> Comparator<T>	frequencyOrder(Multiset<?> multiset) Returns a comparator that imposes ascending frequency ordering on a collection of objects, using multiset to determine the frequency of each object.
static <E> Multiset.Entry<E>	immutableEntry(E e, int n) Returns an immutable multiset entry with the specified element and count.
static <E> Multiset<E>	immutableMultiset() Returns an immutable empty Multiset.
static <E> Multiset<E>	immutableMultiset(E... elements) Returns an immutable Multiset containing the specified elements.
static <E extends Enum<E>> EnumMultiset<E>	newEnumMultiset(Class<E> type) Creates a new empty EnumMultiset.
static <E extends Enum<E>> EnumMultiset<E>	newEnumMultiset(E... elements) Creates a new EnumMultiset containing the specified elements.
static <E extends Enum<E>> EnumMultiset<E>	newEnumMultiset(Iterable<E> elements) Creates a new EnumMultiset containing the specified elements.
static <E> HashMultiset<E>	newHashMultiset() Creates a new empty HashMultiset using the default initial capacity (16 distinct elements) and load factor (0.75).
static <E> HashMultiset<E>	newHashMultiset(E... elements) Creates a new HashMultiset containing the specified elements, using the default initial capacity (16 distinct elements) and load factor (0.75).
static <E> HashMultiset<E>	newHashMultiset(Iterable<? extends E> elements) Creates a new HashMultiset containing the specified elements.
static <E extends Comparable> TreeMultiset<E>	newTreeMultiset() Creates an empty TreeMultiset instance.
static <E> TreeMultiset<E>	newTreeMultiset(Comparator<? super E> c) Creates an empty TreeMultiset instance, sorted according to the specified comparator.
static <E> Multiset<E>	synchronizedMultiset(Multiset<E> multiset) Returns a synchronized (thread-safe) multiset backed by the specified multiset.
static <E> Multiset<E>	unmodifiableMultiset(Multiset<E> multiset) Returns an unmodifiable view of the specified multiset.

Methods inherited from class java.lang.Object

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

Method Detail

newHashMultiset

public static <E> HashMultiset<E> newHashMultiset()

Creates a new empty HashMultiset using the default initial capacity (16 distinct elements) and load factor (0.75).

newHashMultiset

public static <E> HashMultiset<E> newHashMultiset(E... elements)

Creates a new HashMultiset containing the specified elements, using the default initial capacity (16 distinct elements) and load factor (0.75).

Parameters:

elements - the elements that the multiset should contain

newHashMultiset

public static <E> HashMultiset<E> newHashMultiset(Iterable<? extends E> elements)

Creates a new HashMultiset containing the specified elements. If the specified elements is a Multiset, this method behaves identically to HashMultiset.HashMultiset(Multiset). Otherwise, the HashMultiset is created with the default initial capacity (16 distinct elements) and load factor (0.75).

Parameters:

elements - the elements that the multiset should contain

newTreeMultiset

public static <E extends Comparable> TreeMultiset<E> newTreeMultiset()

Creates an empty TreeMultiset instance.

Returns:

a newly-created, initially-empty TreeMultiset

newTreeMultiset

public static <E> TreeMultiset<E> newTreeMultiset(Comparator<? super E> c)

Creates an empty TreeMultiset instance, sorted according to the specified comparator.

Returns:

a newly-created, initially-empty TreeMultiset

newEnumMultiset

public static <E extends Enum<E>> EnumMultiset<E> newEnumMultiset(Class<E> type)

Creates a new empty EnumMultiset.

newEnumMultiset

public static <E extends Enum<E>> EnumMultiset<E> newEnumMultiset(Iterable<E> elements)

Creates a new EnumMultiset containing the specified elements.

Throws:

IllegalArgumentException - if elements is empty

newEnumMultiset

public static <E extends Enum<E>> EnumMultiset<E> newEnumMultiset(E... elements)

Creates a new EnumMultiset containing the specified elements.

Throws:

IllegalArgumentException - if elements is empty

unmodifiableMultiset

public static <E> Multiset<E> unmodifiableMultiset(Multiset<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, whether direct or via its element set or iterator, result in an UnsupportedOperationException.

Parameters:

multiset - the multiset for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified set

synchronizedMultiset

public static <E> Multiset<E> synchronizedMultiset(Multiset<E> multiset)

Returns a synchronized (thread-safe) multiset backed by the specified 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 any of its collection views:

  Multiset<E> m = Multisets.synchronizedMultiset(
      new HashMultiset<E>());
   ...
  Set<E> s = m.elementSet(); // Needn't be in synchronized block
   ...
  synchronized (m) { // Synchronizing on m, not s!
    Iterator<E> i = s.iterator(); // Must be in synchronized block
    while (i.hasNext()) {
      foo(i.next());
    }
  }

Failure to follow this advice may result in non-deterministic behavior.

For a greater degree of concurrency, you may wish to use a ConcurrentMultiset.

Parameters:

multiset - the multiset to be wrapped

Returns:

a synchronized view of the specified multiset

emptyMultiset

public static <E> Multiset<E> emptyMultiset()

Returns the empty multiset (immutable). This multiset is serializable.

immutableEntry

public static <E> Multiset.Entry<E> immutableEntry(E e,
                                                   int n)

Returns an immutable multiset entry with the specified element and count.

Parameters:

e - the element to be associated with the returned entry

n - the count to be associated with the returned entry

forSet

public static <E> Multiset<E> forSet(Set<E> set)

Returns a multiset view of the specified set. The multiset is backed by the set, so changes to the set are reflected in the multiset, and vice versa. If the set is modified while an iteration over the multiset is in progress (except through the iterator's own remove operation) the results of the iteration are undefined.

The multiset supports element removal, which removes the corresponding element from the set. It does not support the add or addAll operations.

The returned multiset will be serializable if the specified set is serializable.

Parameters:

set - the backing set for the returned multiset view

immutableMultiset

public static <E> Multiset<E> immutableMultiset()

Returns an immutable empty Multiset. Equivalent to emptyMultiset(), except that the returned multiset's remove methods throw an UnsupportedOperationException.

immutableMultiset

public static <E> Multiset<E> immutableMultiset(E... elements)

Returns an immutable Multiset containing the specified elements.

Unlike an unmodifiable multiset such as that returned by unmodifiableMultiset(com.google.common.collect.Multiset), which provides a read-only view of an underlying multiset which may itself be mutable, an immutable multiset makes a copy of the original mappings, so that the returned multiset is guaranteed never to change. This is critical, for example, if the multiset is an element of a HashSet or a key in a HashMap.

Parameters:

elements - the elements that the returned multiset should contain

frequencyOrder

public static <T> Comparator<T> frequencyOrder(Multiset<?> multiset)

Returns a comparator that imposes ascending frequency ordering on a collection of objects, using multiset to determine the frequency of each object. This enables a simple idiom for sorting (or maintaining) collections (or arrays) of objects that are sorted by ascending frequency. For example, suppose multiset is a multiset of strings. Then:

  Collections.max(m.elementSet(), frequencyOrder(m));

returns a string that occurs most frequently in multiset.

The returned comparator is a view into the backing multiset, so the comparator's behavior will change if the backing multiset changes. This can be dangerous; for example, if the comparator is used by a TreeSet and the backing multiset changes, the behavior of the TreeSet becomes undefined. Use a copy of the multiset to isolate against such changes when necessary.

Parameters:

multiset - the multiset specifying the frequency of objects to compare