com.google.common.collect
Class Multisets

java.lang.Object
  extended by 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>
forSet(Set<E> set)
          Returns a multiset view of the specified set.
static
<T> Ordering<T>
frequencyOrder(Multiset<?> multiset)
          Returns a comparator that orders elements according to their increasing frequency in a multiset.
static
<E> Multiset.Entry<E>
immutableEntry(E e, int n)
          Returns an immutable multiset entry with the specified element and count.
static
<E extends Enum<E>>
EnumMultiset<E>
newEnumMultiset(Class<E> type)
          Creates an empty EnumMultiset.
static
<E extends Enum<E>>
EnumMultiset<E>
newEnumMultiset(E... elements)
          Creates an EnumMultiset containing the specified elements.
static
<E extends Enum<E>>
EnumMultiset<E>
newEnumMultiset(Iterable<E> elements)
          Creates an EnumMultiset containing the specified elements.
static
<E> HashMultiset<E>
newHashMultiset()
          Creates an empty HashMultiset using the default initial capacity (16 distinct elements).
static
<E> HashMultiset<E>
newHashMultiset(E... elements)
          Creates a HashMultiset containing the specified elements, using the default initial capacity (16 distinct elements).
static
<E> HashMultiset<E>
newHashMultiset(Iterable<? extends E> elements)
          Creates a 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 an empty HashMultiset using the default initial capacity (16 distinct elements).


newHashMultiset

public static <E> HashMultiset<E> newHashMultiset(E... elements)
Creates a HashMultiset containing the specified elements, using the default initial capacity (16 distinct elements).

Parameters:
elements - the elements that the multiset should contain

newHashMultiset

public static <E> HashMultiset<E> newHashMultiset(Iterable<? extends E> elements)
Creates a HashMultiset containing the specified elements.

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 an empty EnumMultiset.


newEnumMultiset

public static <E extends Enum<E>> EnumMultiset<E> newEnumMultiset(Iterable<E> elements)
Creates an EnumMultiset containing the specified elements.

Throws:
IllegalArgumentException - if elements is empty

newEnumMultiset

public static <E extends Enum<E>> EnumMultiset<E> newEnumMultiset(E... elements)
Creates an 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 result in an UnsupportedOperationException.

Parameters:
multiset - the multiset for which an unmodifiable view is to be generated
Returns:
an unmodifiable view of the multiset

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, all access to the backing multiset must go 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 use a ConcurrentMultiset.

Parameters:
multiset - the multiset to be wrapped
Returns:
a synchronized view of the specified multiset

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
Throws:
IllegalArgumentException - if n is negative

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. The multiset is threadsafe if the set is threadsafe.

Parameters:
set - the backing set for the returned multiset view

frequencyOrder

public static <T> Ordering<T> frequencyOrder(Multiset<?> multiset)
Returns a comparator that orders elements according to their increasing frequency in a multiset. For example, suppose m is a non-empty multiset of strings. Then:
  Collections.max(m.elementSet(), frequencyOrder(m));
returns a string that occurs most frequently in m. (Warning: in this example, Collections.max throws NoSuchElementException when m is empty.)

The returned Ordering is a view into the backing multiset, so the ordering's behavior will change if the backing multiset changes. This can be dangerous; for example, if the ordering 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 frequencies of the objects to compare