Top Description Inners Constructors Methods
com.google.common.collect

public abstract Class ForwardingMultiset<E extends @Nullable Object>

extends ForwardingCollection<E extends @Nullable Object>
implements Multiset<E extends @Nullable Object>
Class Inheritance
All Implemented Interfaces
com.google.common.collect.Multiset, java.util.Collection, java.lang.Iterable
Known Direct Subclasses
com.google.common.collect.ForwardingSortedMultiset, com.google.common.collect.Multisets.UnmodifiableMultiset, com.google.common.collect.DescendingMultiset
Annotations
@GwtCompatible
@ElementTypesAreNonnullByDefault
Imports
com.google.common.annotations.GwtCompatible, com.google.common.base.Objects, com.google.errorprone.annotations.CanIgnoreReturnValue, java.util.Collection, .Iterator, .Set, javax.annotation.CheckForNull, org.checkerframework.checker.nullness.qual.Nullable
A multiset which forwards all its method calls to another multiset. Subclasses should override one or more methods to modify the behavior of the backing multiset as desired per the decorator pattern.

Warning

The methods of ForwardingMultiset forward indiscriminately to the methods of the delegate. For example, overriding add(Object, int) alone will not change the behavior of add(Object), which can lead to unexpected behavior. In this case, you should override add(Object) as well, either providing your own implementation, or delegating to the provided standardAdd method.

default method warning: This class does not forward calls to default methods. Instead, it inherits their default implementations. When those implementations invoke methods, they invoke methods on the ForwardingMultiset.

The standard methods and any collection views they return are not guaranteed to be thread-safe, even when all of the methods that they depend on are thread-safe.

Authors
Kevin Bourrillion, Louis Wasserman
Since
2.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
protected class
ForwardingMultiset.StandardElementSet

A sensible implementation of Multiset#elementSet in terms of the following methods: ForwardingMultiset#clear, ForwardingMultiset#contains, ForwardingMultiset#containsAll, ForwardingMultiset#count, ForwardingMultiset#isEmpty, the Set#size and Set#iterator methods of ForwardingMultiset#entrySet, and ForwardingMultiset#remove(Object, int).

Constructor Summary

AccessConstructor and Description
protected
ForwardingMultiset()

Constructor for use by subclasses.

Method Summary

Modifier and TypeMethod and Description
public int
add(E
the element to add occurrences of; may be null only if explicitly allowed by the implementation
element, int
the number of occurrences of the element to add. May be zero, in which case no change will be made.
occurrences)

Implements com.google.common.collect.Multiset.add.

Adds a number of occurrences of an element to this multiset.
public int
count(Object
the element to count occurrences of
element)

Implements com.google.common.collect.Multiset.count.

Returns the number of occurrences of an element in this multiset (the count of the element).
protected abstract Multiset<E>
delegate()

Implements abstract com.google.common.collect.ForwardingCollection.delegate.

Returns the backing delegate instance that methods are forwarded to.
public Set<E>
elementSet()

Implements com.google.common.collect.Multiset.elementSet.

Returns the set of distinct elements contained in this multiset.
public Set<Multiset.Entry<E>>
entrySet()

Implements com.google.common.collect.Multiset.entrySet.

Returns a view of the contents of this multiset, grouped into Multiset.Entry instances, each providing an element of the multiset and the count of that element.
public boolean
equals(Object
object to be compared for equality with this collection
object)

Overrides java.lang.Object.equals.

Implements com.google.common.collect.Multiset.equals, java.util.Collection.equals.

Compares the specified object with this multiset for equality.
public int
hashCode()

Overrides java.lang.Object.hashCode.

Implements com.google.common.collect.Multiset.hashCode, java.util.Collection.hashCode.

Returns the hash code for this multiset.
public int
remove(Object
the element to conditionally remove occurrences of
element, int
the number of occurrences of the element to remove. May be zero, in which case no change will be made.
occurrences)

Implements com.google.common.collect.Multiset.remove.

Removes a number of occurrences of the specified element from this multiset.
public int
setCount(E
the element to add or remove occurrences of; may be null only if explicitly allowed by the implementation
element, int
the desired count of the element in this multiset
count)

Implements com.google.common.collect.Multiset.setCount.

Adds or removes the necessary occurrences of an element such that the element attains the desired count.
public boolean
setCount(E
the element to conditionally set the count of; may be null only if explicitly allowed by the implementation
element, int
the expected present count of the element in this multiset
oldCount, int
the desired count of the element in this multiset
newCount)

Implements com.google.common.collect.Multiset.setCount.

Conditionally sets the count of an element to a new value, as described in setCount(Object, int), provided that the element has the expected current count.
protected boolean
standardAdd(E element)

A sensible definition of add(Object) in terms of add(Object, int).

protected boolean
standardAddAll(Collection<? extends E> elementsToAdd)

Overrides com.google.common.collect.ForwardingCollection.standardAddAll.

A sensible definition of addAll(Collection) in terms of add(Object) and add(Object, int).
protected void
standardClear()

Overrides com.google.common.collect.ForwardingCollection.standardClear.

A sensible definition of clear in terms of the iterator method of entrySet.
protected boolean
standardContains(Object object)

Overrides com.google.common.collect.ForwardingCollection.standardContains.

A sensible definition of contains in terms of count.
protected int
standardCount(Object object)

A sensible, albeit inefficient, definition of count in terms of entrySet.

protected boolean
standardEquals(Object object)

A sensible, albeit inefficient, definition of equals in terms of entrySet().size() and count.

protected int
standardHashCode()

A sensible definition of hashCode as entrySet().hashCode() .

protected Iterator<E>
standardIterator()

A sensible definition of iterator in terms of entrySet and remove(Object).

protected boolean
standardRemove(Object element)

Overrides com.google.common.collect.ForwardingCollection.standardRemove.

A sensible definition of remove(Object) in terms of remove(Object, int).
protected boolean
standardRemoveAll(Collection<?> elementsToRemove)

Overrides com.google.common.collect.ForwardingCollection.standardRemoveAll.

A sensible definition of removeAll in terms of the removeAll method of elementSet.
protected boolean
standardRetainAll(Collection<?> elementsToRetain)

Overrides com.google.common.collect.ForwardingCollection.standardRetainAll.

A sensible definition of retainAll in terms of the retainAll method of elementSet.
protected int
standardSetCount(E element, int count)

A sensible definition of setCount(Object, int) in terms of count(Object), add(Object, int), and remove(Object, int).

protected boolean
standardSetCount(E element, int oldCount, int newCount)

A sensible definition of setCount(Object, int, int) in terms of count(Object) and setCount(Object, int).

protected int
standardSize()

A sensible, albeit inefficient, definition of size in terms of entrySet.

protected String
standardToString()

Overrides com.google.common.collect.ForwardingCollection.standardToString.

A sensible definition of toString as entrySet().toString() .
Inherited from com.google.common.collect.ForwardingCollection:
addaddAllclearcontainscontainsAllisEmptyiteratorremoveremoveAllretainAllsizestandardContainsAllstandardIsEmptystandardToArraystandardToArraytoArraytoArray

Constructor Detail

ForwardingMultisetback to summary
protected ForwardingMultiset()

Constructor for use by subclasses.

Method Detail

addback to summary
public int add(E element, int occurrences)

Implements com.google.common.collect.Multiset.add.

Doc from com.google.common.collect.Multiset.add.

Adds a number of occurrences of an element to this multiset. Note that if occurrences == 1, this method has the identical effect to add(Object). This method is functionally equivalent (except in the case of overflow) to the call addAll(Collections.nCopies(element, occurrences)), which would presumably perform much more poorly.

Parameters
element:E

the element to add occurrences of; may be null only if explicitly allowed by the implementation

occurrences:int

the number of occurrences of the element to add. May be zero, in which case no change will be made.

Returns:int

the count of the element before the operation; possibly zero

Annotations
@CanIgnoreReturnValue
@Override
countback to summary
public int count(Object element)

Implements com.google.common.collect.Multiset.count.

Doc from com.google.common.collect.Multiset.count.

Returns the number of occurrences of an element in this multiset (the count of the element). Note that for an Object#equals-based multiset, this gives the same result as Collections#frequency (which would presumably perform more poorly).

Note

the utility method Iterables#frequency generalizes this operation; it correctly delegates to this method when dealing with a multiset, but it can also accept any other iterable type.

Parameters
element:Object

the element to count occurrences of

Returns:int

the number of occurrences of the element in this multiset; possibly zero but never negative

Annotations
@Override
delegateback to summary
protected abstract Multiset<E> delegate()

Implements abstract com.google.common.collect.ForwardingCollection.delegate.

Doc from com.google.common.collect.ForwardingObject.delegate.

Returns the backing delegate instance that methods are forwarded to. Abstract subclasses generally override this method with an abstract method that has a more specific return type, such as ForwardingSet#delegate. Concrete subclasses override this method to supply the instance being decorated.

Annotations
@Override
elementSetback to summary
public Set<E> elementSet()

Implements com.google.common.collect.Multiset.elementSet.

Doc from com.google.common.collect.Multiset.elementSet.

Returns the set of distinct elements contained in this multiset. The element set is backed by the same data as the multiset, so any change to either is immediately reflected in the other. The order of the elements in the element set is unspecified.

If the element set supports any removal operations, these necessarily cause all occurrences of the removed element(s) to be removed from the multiset. Implementations are not expected to support the add operations, although this is possible.

A common use for the element set is to find the number of distinct elements in the multiset: elementSet().size().

Returns:Set<E>

a view of the set of distinct elements in this multiset

Annotations
@Override
entrySetback to summary
public Set<Multiset.Entry<E>> entrySet()

Implements com.google.common.collect.Multiset.entrySet.

Doc from com.google.common.collect.Multiset.entrySet.

Returns a view of the contents of this multiset, grouped into Multiset.Entry instances, each providing an element of the multiset and the count of that element. This set contains exactly one entry for each distinct element in the multiset (thus it always has the same size as the elementSet). The order of the elements in the element set is unspecified.

The entry set is backed by the same data as the multiset, so any change to either is immediately reflected in the other. However, multiset changes may or may not be reflected in any Entry instances already retrieved from the entry set (this is implementation-dependent). Furthermore, implementations are not required to support modifications to the entry set at all, and the Entry instances themselves don't even have methods for modification. See the specific implementation class for more details on how its entry set handles modifications.

Returns:Set<Multiset.Entry<E>>

a set of entries representing the data of this multiset

Annotations
@Override
equalsback to summary
public boolean equals(Object object)

Overrides java.lang.Object.equals.

Implements com.google.common.collect.Multiset.equals, java.util.Collection.equals.

Doc from com.google.common.collect.Multiset.equals.

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, regardless of order.

Parameters
object:Object

Doc from java.util.Collection.equals.

object to be compared for equality with this collection

Returns:boolean

Doc from java.util.Collection.equals.

true if the specified object is equal to this collection

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Implements com.google.common.collect.Multiset.hashCode, java.util.Collection.hashCode.

Doc from com.google.common.collect.Multiset.hashCode.

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

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

over all distinct elements in the multiset. It follows that a multiset and its entry set always have the same hash code.

Returns:int

Doc from java.util.Collection.hashCode.

the hash code value for this collection

Annotations
@Override
removeback to summary
public int remove(Object element, int occurrences)

Implements com.google.common.collect.Multiset.remove.

Doc from com.google.common.collect.Multiset.remove.

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. Note that if occurrences == 1, this is functionally equivalent to the call remove(element).

Parameters
element:Object

the element to conditionally remove occurrences of

occurrences:int

the number of occurrences of the element to remove. May be zero, in which case no change will be made.

Returns:int

the count of the element before the operation; possibly zero

Annotations
@CanIgnoreReturnValue
@Override
setCountback to summary
public int setCount(E element, int count)

Implements com.google.common.collect.Multiset.setCount.

Doc from com.google.common.collect.Multiset.setCount.

Adds or removes the necessary occurrences of an element such that the element attains the desired count.

Parameters
element:E

the element to add or remove occurrences of; may be null only if explicitly allowed by the implementation

count:int

the desired count of the element in this multiset

Returns:int

the count of the element before the operation; possibly zero

Annotations
@CanIgnoreReturnValue
@Override
setCountback to summary
public boolean setCount(E element, int oldCount, int newCount)

Implements com.google.common.collect.Multiset.setCount.

Doc from com.google.common.collect.Multiset.setCount.

Conditionally sets the count of an element to a new value, as described in setCount(Object, int), provided that the element has the expected current count. If the current count is not oldCount, no change is made.

Parameters
element:E

the element to conditionally set the count of; may be null only if explicitly allowed by the implementation

oldCount:int

the expected present count of the element in this multiset

newCount:int

the desired count of the element in this multiset

Returns:boolean

true if the condition for modification was met. This implies that the multiset was indeed modified, unless oldCount == newCount.

Annotations
@CanIgnoreReturnValue
@Override
standardAddback to summary
protected boolean standardAdd(E element)

A sensible definition of add(Object) in terms of add(Object, int). If you override add(Object, int), you may wish to override add(Object) to forward to this implementation.

Since
7.0
standardAddAllback to summary
protected boolean standardAddAll(Collection<? extends E> elementsToAdd)

Overrides com.google.common.collect.ForwardingCollection.standardAddAll.

A sensible definition of addAll(Collection) in terms of add(Object) and add(Object, int). If you override either of these methods, you may wish to override addAll(Collection) to forward to this implementation.

Annotations
@Override
Since
7.0
standardClearback to summary
protected void standardClear()

Overrides com.google.common.collect.ForwardingCollection.standardClear.

A sensible definition of clear in terms of the iterator method of entrySet. If you override entrySet, you may wish to override clear to forward to this implementation.

Annotations
@Override
Since
7.0
standardContainsback to summary
protected boolean standardContains(Object object)

Overrides com.google.common.collect.ForwardingCollection.standardContains.

A sensible definition of contains in terms of count. If you override count, you may wish to override contains to forward to this implementation.

Annotations
@Override
Since
7.0
standardCountback to summary
protected int standardCount(Object object)

A sensible, albeit inefficient, definition of count in terms of entrySet. If you override entrySet, you may wish to override count to forward to this implementation.

Since
7.0
standardEqualsback to summary
protected boolean standardEquals(Object object)

A sensible, albeit inefficient, definition of equals in terms of entrySet().size() and count. If you override either of these methods, you may wish to override equals to forward to this implementation.

Since
7.0
standardHashCodeback to summary
protected int standardHashCode()

A sensible definition of hashCode as entrySet().hashCode() . If you override entrySet, you may wish to override hashCode to forward to this implementation.

Since
7.0
standardIteratorback to summary
protected Iterator<E> standardIterator()

A sensible definition of iterator in terms of entrySet and remove(Object). If you override either of these methods, you may wish to override iterator to forward to this implementation.

Since
7.0
standardRemoveback to summary
protected boolean standardRemove(Object element)

Overrides com.google.common.collect.ForwardingCollection.standardRemove.

A sensible definition of remove(Object) in terms of remove(Object, int). If you override remove(Object, int), you may wish to override remove(Object) to forward to this implementation.

Annotations
@Override
Since
7.0
standardRemoveAllback to summary
protected boolean standardRemoveAll(Collection<?> elementsToRemove)

Overrides com.google.common.collect.ForwardingCollection.standardRemoveAll.

A sensible definition of removeAll in terms of the removeAll method of elementSet. If you override elementSet, you may wish to override removeAll to forward to this implementation.

Annotations
@Override
Since
7.0
standardRetainAllback to summary
protected boolean standardRetainAll(Collection<?> elementsToRetain)

Overrides com.google.common.collect.ForwardingCollection.standardRetainAll.

A sensible definition of retainAll in terms of the retainAll method of elementSet. If you override elementSet, you may wish to override retainAll to forward to this implementation.

Annotations
@Override
Since
7.0
standardSetCountback to summary
protected int standardSetCount(E element, int count)

A sensible definition of setCount(Object, int) in terms of count(Object), add(Object, int), and remove(Object, int). entrySet(). If you override any of these methods, you may wish to override setCount(Object, int) to forward to this implementation.

Since
7.0
standardSetCountback to summary
protected boolean standardSetCount(E element, int oldCount, int newCount)

A sensible definition of setCount(Object, int, int) in terms of count(Object) and setCount(Object, int). If you override either of these methods, you may wish to override setCount(Object, int, int) to forward to this implementation.

Since
7.0
standardSizeback to summary
protected int standardSize()

A sensible, albeit inefficient, definition of size in terms of entrySet. If you override entrySet, you may wish to override size to forward to this implementation.

Since
7.0
standardToStringback to summary
protected String standardToString()

Overrides com.google.common.collect.ForwardingCollection.standardToString.

A sensible definition of toString as entrySet().toString() . If you override entrySet, you may wish to override toString to forward to this implementation.

Annotations
@Override
Since
7.0
com.google.common.collect back to summary

protected Class ForwardingMultiset.StandardElementSet

extends Multisets.ElementSet<E extends @Nullable Object>
Class Inheritance
A sensible implementation of Multiset#elementSet in terms of the following methods: ForwardingMultiset#clear, ForwardingMultiset#contains, ForwardingMultiset#containsAll, ForwardingMultiset#count, ForwardingMultiset#isEmpty, the Set#size and Set#iterator methods of ForwardingMultiset#entrySet, and ForwardingMultiset#remove(Object, int). In many situations, you may wish to override ForwardingMultiset#elementSet to forward to this implementation or a subclass thereof.
Since
10.0

Constructor Summary

AccessConstructor and Description
public
StandardElementSet()

Constructor for use by subclasses.

Method Summary

Modifier and TypeMethod and Description
public Iterator<E>
iterator()

Implements abstract com.google.common.collect.Multisets.ElementSet.iterator.

Implements java.util.Set.iterator, java.util.Collection.iterator.

Returns an iterator over the elements in this set.
pack-priv Multiset<E>
multiset()

Implements abstract com.google.common.collect.Multisets.ElementSet.multiset.

Inherited from com.google.common.collect.Multisets.ElementSet:
clearcontainscontainsAllisEmptyremovesize

Constructor Detail

StandardElementSetback to summary
public StandardElementSet()

Constructor for use by subclasses.

Method Detail

iteratorback to summary
public Iterator<E> iterator()

Implements abstract com.google.common.collect.Multisets.ElementSet.iterator.

Implements java.util.Set.iterator, java.util.Collection.iterator.

Doc from java.util.Set.iterator.

Returns an iterator over the elements in this set. The elements are returned in no particular order (unless this set is an instance of some class that provides a guarantee).

Returns:Iterator<E>

an iterator over the elements in this set

Annotations
@Override
multisetback to summary
pack-priv Multiset<E> multiset()

Implements abstract com.google.common.collect.Multisets.ElementSet.multiset.

Annotations
@Override