com.google.common.collect
Interface Multiset<E>

All Superinterfaces:

Collection<E>, Iterable<E>

All Known Implementing Classes:

AbstractMultiset, ConcurrentMultiset, EnumMultiset, ForwardingMultiset, HashMultiset, LinkedHashMultiset, LinkedListMultiset, TreeMultiset

public interface Multiset<E>
extends Collection<E>

An unordered collection similar to a Set, but which may contain duplicate elements.

Author:

Kevin Bourrillion

Nested Class Summary

static interface

Multiset.Entry<E> A multiset entry (element-count pair).

Method Summary

boolean	add(E element, int occurrences) Adds a number of occurrences of the specified element to this multiset.
int	count(Object element) Returns the number of occurrences of the specified element in this multiset.
Set<E>	elementSet() Returns a view of the elements of this multiset as a set.
Set<Multiset.Entry<E>>	entrySet() Returns the data of this multiset as a set of Entry instances.
boolean	equals(Object object) Compares the specified object with this multiset for equality.
int	hashCode() Returns the hash code for this multiset.
int	remove(Object element, int occurrences) Removes a number of occurrences of the specified element from this multiset.
int	removeAllOccurrences(Object element) Removes all occurrences of the specified element from this multiset.

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

count

int count(@Nullable
          Object element)

Returns the number of occurrences of the specified element in this multiset.

Parameters:

element - the element to look for

Returns:

the nonnegative number of occurrences of the element

See Also:

Iterables.frequency(java.lang.Iterable, java.lang.Object)

add

boolean add(@Nullable
            E element,
            int occurrences)

Adds a number of occurrences of the specified element to this multiset.

Parameters:

element - the element to add

occurrences - the number of occurrences to add

Returns:

true if the collection changed as a result (this should always be the case unless occurrences is zero)

Throws:

IllegalArgumentException - if occurrences is negative

remove

int remove(@Nullable
           Object element,
           int occurrences)

Removes a number of occurrences of the specified element from this multiset. If the multiset contains fewer than this number of occurrences to begin with, all occurrences will be removed.

Parameters:

element - the element whose occurrences should be removed

occurrences - the number of occurrences of this element to remove

Returns:

the number of occurrences that were successfully removed (zero if the element was not present)

Throws:

IllegalArgumentException - if occurrences is negative

removeAllOccurrences

int removeAllOccurrences(@Nullable
                         Object element)

Removes all occurrences of the specified element from this multiset. This method complements remove(java.lang.Object, int), which removes only one occurrence at a time.

Parameters:

element - the element whose occurrences should all be removed

Returns:

the number of occurrences successfully removed, possibly zero

elementSet

Set<E> elementSet()

Returns a view of the elements of this multiset as a set. All remove operations on the returned set "write through" to the underlying multiset, removing all occurrences of the given elements. No add operations are supported. Note that you can use elementSet().size() to find the number of distinct elements in this multiset.

Returns:

the distinct elements of this multiset, viewed as a set

entrySet

Set<Multiset.Entry<E>> entrySet()

Returns the data of this multiset as a set of Entry instances. This set contains precisely one Entry instance for each distinct element of the multiset. The iteration order of this set is implementation-dependent.

Returns:

the entries of this multiset, viewed as a set

equals

boolean equals(@Nullable
               Object object)

Compares the specified object with this multiset for equality. Returns true if the given object is also a multiset and contains equal elements with equal counts.

Specified by:

equals in interface Collection<E>

Overrides:

equals in class Object

hashCode

int hashCode()

Returns the hash code for this multiset. This is defined as the sum of

  (element == null ? 0 : element.hashCode()) ^ count(element)

over all elements in the multiset.

Specified by:

hashCode in interface Collection<E>

Overrides:

hashCode in class Object