MultiSet (TestHelpers 1.0-SNAPSHOT API)

Type Parameters:

T - the class of the elements of this multi-set.

All Superinterfaces:

Iterable<T>

All Known Subinterfaces:

SortedMultiSet<T>

All Known Implementing Classes:

AbstractMultiSet, CollectionsExt.AbstractImmutableMultiSet, CollectionsExt.ImmutableMultiSet, CollectionsExt.ImmutableSortedMultiSet, HashMultiSet, TreeMultiSet
```
public interface MultiSet<T>
extends Iterable<T>
```
Represents a set with multiplicities. Mathematically this is something between a set and a family. Note that implementations of this kind of set need not support null elements.
Allows also to create an immutable MultiSet either from a set or as a copy of another MultiSet.
Note that this should extend Collection, but still does not *****. maybe it should even extend Set.

Version:

1.0

Author:

Ernst Reissner

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface MultiSet.Multiplicity
Represents the multiplicity of an entry of the enclosing multi-set.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`MultiSet.Multiplicity` Represents the multiplicity of an entry of the enclosing multi-set.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`add(T obj)` Adds `obj` to this `MultiSet`.
`boolean`	`addAll(MultiSet<? extends T> mvs)` Adds `mvs` elementwise to this multi set taking multiplicities into account and returns whether this caused a change of the underlying set. **** strange implementation; also: change
`boolean`	`addAll(Set<? extends T> set)` Adds `set` elementwise to this multi set increasing multiplicities and returns whether this caused a change of the underlying set. **** strange implementation; also: change
`int`	`addWithMult(T obj)` Adds `obj` to this `MultiSet` and returns the new multiplicity of this object.
`int`	`addWithMult(T obj, int addMult)` Increases the multiplicity of `obj` in this `MultiSet` by the specified value `addMult` and returns the new multiplicity of this object.
`void`	`clear()` Removes all of the elements from this `MultiSet`.
`boolean`	`contains(Object obj)` Returns `true` if this `MultiSet` contains the specified element.
`boolean`	`containsAll(Collection<?> coll)` Returns `true` if this `MultiSet` contains all of the elements in the specified collection with strictly positive multiplicity.
`boolean`	`equals(Object obj)` Returns `true` if and only if `obj` is also a `MultiSet` and contains the same elements with the same multiplicities as this one.
`Map<T,MultiSet.Multiplicity>`	`getMap()` Returns a view of the underlying map of this `MultiSet` as a map mapping each entry to its multiplicity.
`int`	`getMaxMult()` Returns the maximal multiplicity of an element in this set.
`int`	`getMultiplicity(Object obj)` Returns the multiplicity with which the given object occurs within this set.
`MultiSet.Multiplicity`	`getMultiplicityObj(Object obj)` Returns the multiplicity object of the given object in this set or `null`.
`Object`	`getObjWithMaxMult()` Returns one of the elements in this multiple set with maximal multiplicity.
`Set<T>`	`getSet()` Returns a view of the underlying set of this `MultiSet`.
`Set<Map.Entry<T,MultiSet.Multiplicity>>`	`getSetWithMults()` Returns a Set view of the mapping from the element of this `MultiSet` to the according multiplicities.
`int`	`hashCode()`
`boolean`	`isEmpty()` Returns whether this multiple set contains no element.
`MultiSetIterator<T>`	`iterator()` Returns an iterator over the elements in this collection which emits each element exactly once, without regarding its multiplicity
`boolean`	`remove(Object obj)` Removes all instances of the specified element from this `MultiSet`, if it is present with nontrivial multiplicity.
`boolean`	`removeAll(Collection<?> coll)` Removes all this `MultiSet`'s elements that are also contained in the specified collection.
`int`	`removeWithMult(Object obj)` Decrements the multiplicity of `obj` in this `MultiSet` if it is present and returns the old multiplicity of `obj`; If this is `0` returns without altering this `MultiSet`.
`int`	`removeWithMult(Object obj, int removeMult)` Decreases the multiplicity of `obj` in this `MultiSet` by the specified value `removeMult` if possible and returns the old multiplicity of `obj`.
`boolean`	`retainAll(Collection<?> coll)` Retains only the elements in this `MultiSet` that are contained in the specified collection.
`int`	`setMultiplicity(T obj, int newMult)` Sets the multiplicity of `obj` to the value specified by `mult`.
`int`	`size()` Returns the number of pairwise different elements in this `MultiSet`.
`int`	`sizeWithMult()` Returns the number of elements in this `MultiSet` counted with multiplicities.
`Object[]`	`toArray()` Returns an array containing all of the elements in this `MultiSet` exactly once, ignoring its multiplicity
`T[]`	`toArray(T[] arr)` Returns an array containing all of the elements in this `MultiSet`; the runtime type of the returned array is that of the specified array.
`String`	`toString()`

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Method Detail
  - size
```
int size()
```
    Returns the number of pairwise different elements in this MultiSet. If this MultiSet contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
    
    Returns:
    
    the number of elements in this MultiSet each multiple element counted as a single one.
    
    See Also:
    
    sizeWithMult()
  - sizeWithMult
```
int sizeWithMult()
```
    Returns the number of elements in this MultiSet counted with multiplicities. If this MultiSet contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
    
    Returns:
    
    the number of elements in this MultiSet counted with multiplicities, provided this does not exceed Integer.MAX_VALUE; otherwise just Integer.MAX_VALUE.
    
    See Also:
    
    size()
  - isEmpty
```
boolean isEmpty()
```
    Returns whether this multiple set contains no element.
    
    Returns:
    
    whether this multiple set contains no element.
  - getObjWithMaxMult
```
Object getObjWithMaxMult()
```
    Returns one of the elements in this multiple set with maximal multiplicity. The return value is null if and only if this set is empty.
    
    Returns:
    
    a Object o != null with maximal multiplicity or null if this multiple set is empty.
    
    See Also:
    
    isEmpty()
  - getMaxMult
```
int getMaxMult()
```
    Returns the maximal multiplicity of an element in this set. In particular for empty sets returns 0.
    
    Returns:
    
    a non-negative int value which is the maximal mutliplicity of an element in this set. In particular this is 0 if and only if this set is empty.
  - getMultiplicity
```
int getMultiplicity(Object obj)
```
    Returns the multiplicity with which the given object occurs within this set.
    
    Parameters:
    
    obj - an Object and not null.
    
    Returns:
    
    a non-negative int value which is the mutliplicity of the given element in this set. In particular this is 0 if and only if obj is an instance which is not in this set.
    
    Throws:
    
    NullPointerException - for obj==null.
    
    See Also:
    
    setMultiplicity(Object, int), getMultiplicityObj(Object)
  - getMultiplicityObj
```
MultiSet.Multiplicity getMultiplicityObj(Object obj)
```
    Returns the multiplicity object of the given object in this set or null.
    
    Parameters:
    
    obj - an Object and not null.
    
    Returns:
    
    If obj is an instance which is in this set, a multiplicity object wrapping the multiplicity is returned. If obj is an instance which is not in this set, null is returned.
    
    Throws:
    
    NullPointerException - for obj==null.
    
    See Also:
    
    getMultiplicity(Object)
  - contains
```
boolean contains(Object obj)
```
    Returns true if this MultiSet contains the specified element. More formally, returns true if and only if this MultiSet contains at least one element e such that (o==null ? e==null : o.equals(e)).
    
    Parameters:
    
    obj - element (not null) whose presence in this MultiSet is to be tested.
    
    Returns:
    
    true if this MultiSet contains the specified element.
    
    Throws:
    
    NullPointerException - for obj==null.
  - iterator
```
MultiSetIterator<T> iterator()
```
    Returns an iterator over the elements in this collection which emits each element exactly once, without regarding its multiplicity. For certain implementations, the iterator returned does not allow modifications of the underlying (multi-)set.
    
    Specified by:
    
    iterator in interface Iterable<T>
    
    Returns:
    
    an Iterator over the elements in this collection considering each element exactly once ignoring its multiplicity.
  - toArray
```
Object[] toArray()
```
    Returns an array containing all of the elements in this MultiSet exactly once, ignoring its multiplicity.
    The returned array will be "safe" in that no references to it are maintained by this MultiSet. (In other words, this method must allocate a new array even if this MultiSet is backed by an array). The caller is thus free to modify the returned array.
    
    Returns:
    
    an array containing all of the elements in this collection
    
    See Also:
    
    iterator()
  - toArray
```
T[] toArray(T[] arr)
```
    Returns an array containing all of the elements in this MultiSet; the runtime type of the returned array is that of the specified array. If the MultiSet fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this MultiSet.
    If this MultiSet fits in the specified array with room to spare (i.e., the array has more elements than this MultiSet), the elementin the array immediately following the end of the MultiSet is set to null. This is useful in determining the length of this MultiSet because this MultiSet does not contain any null elements.
    Suppose l is a List known to contain only strings. The following code can be used to dump the list into a newly allocated array of String:
```
     String[] x = (String[]) v.toArray(new String[0]);
 
```
    Note that toArray(new Object[0]) is identical in function to toArray().
    Parameters:
    
    arr - the array into which the elements of this MultiSet are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
    
    Returns:
    
    an array containing each elements of this MultiSet exactly once.
    
    Throws:
    
    ArrayStoreException - the runtime type of the specified array is not a supertype of the runtime type of every element in this MultiSet.
    
    NullPointerException - if the specified array is null.
  - addWithMult
```
int addWithMult(T obj)
```
    Adds obj to this MultiSet and returns the new multiplicity of this object. In other words, increments the multiplicity of obj by one. This is a special case of addWithMult(Object obj, int addMult) with addMult==1.
    
    Parameters:
    
    obj - a Object. Note that this object may not be null.
    
    Returns:
    
    a strictly positive int value: the new multiplicity of obj.
    
    Throws:
    
    NullPointerException - if the specified element is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - addWithMult
```
int addWithMult(T obj,
                int addMult)
```
    Increases the multiplicity of obj in this MultiSet by the specified value addMult and returns the new multiplicity of this object. This generalizes addWithMult(Object obj) with addMult==1.
    
    Parameters:
    
    obj - an Object instance.
    
    addMult - a non-negative integer specifying the multiplicity with which obj is to be added.
    
    Returns:
    
    a non-negative int value: the new multiplicity of obj.
    
    Throws:
    
    IllegalArgumentException - for addMult < 0.
    
    NullPointerException - for obj==null provided addMult ≥ 0.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - add
```
boolean add(T obj)
```
    Adds obj to this MultiSet. In other words, increments the multiplicity of obj by one. Returns true if this MultiSet interpreted as a set changed as a result of the call. (Returns false if this MultiSet already contains the specified element (with nontrivial multiplicity).
    
    Parameters:
    
    obj - element the multiplicity of which in this MultiSet is to be increased by one. Note that this may not be null.
    
    Returns:
    
    true if and only if the multiplicity of the specified element was 0 before the call of this method.
    
    Throws:
    
    NullPointerException - if the specified element is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - removeWithMult
```
int removeWithMult(Object obj)
```
    Decrements the multiplicity of obj in this MultiSet if it is present and returns the old multiplicity of obj; If this is 0 returns without altering this MultiSet.
    
    Parameters:
    
    obj - a Object. Note that this object may not be null.
    
    Returns:
    
    a non-negative int value: the old multiplicity of obj before a potential modification of this MultiSet.
    
    Throws:
    
    NullPointerException - if the specified element is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - removeWithMult
```
int removeWithMult(Object obj,
                   int removeMult)
```
    Decreases the multiplicity of obj in this MultiSet by the specified value removeMult if possible and returns the old multiplicity of obj.
    
    Parameters:
    
    obj - an Object instance.
    
    removeMult - a non-negative integer specifying the multiplicity with which obj is to be removed.
    
    Returns:
    
    a non-negative int value: the old multiplicity of obj before a potential modification of this MultiSet.
    
    Throws:
    
    NullPointerException - for obj == null.
    
    IllegalArgumentException - for removeMult < 0 and also if removeMult - obj.getMultiplicity() < 0.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - remove
```
boolean remove(Object obj)
```
    Removes all instances of the specified element from this MultiSet, if it is present with nontrivial multiplicity. More formally, immediately after having (successively) invoked s.remove(o), the condition s.contains(o) == false is satisfied. Returns true if this MultiSet contained the specified element (or equivalently, if (the underlying set of) this MultiSet changed as a result of the call).
    
    Parameters:
    
    obj - element the multiplicity of which in this MultiSet is to be increased by one.
    
    Returns:
    
    true if and only if this MultiSet changed as a result of the call.
    
    Throws:
    
    NullPointerException - if the specified element is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - setMultiplicity
```
int setMultiplicity(T obj,
                    int newMult)
```
    Sets the multiplicity of obj to the value specified by mult.
    
    Parameters:
    
    obj - an Object instance.
    
    newMult - a non-negative int value.
    
    Returns:
    
    the old multiplicity of obj as a non-negative int value.
    
    Throws:
    
    IllegalArgumentException - if either obj == null or mult ≤ 0.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
    
    See Also:
    
    getMultiplicity(Object)
  - containsAll
```
boolean containsAll(Collection<?> coll)
```
    Returns true if this MultiSet contains all of the elements in the specified collection with strictly positive multiplicity.
    
    Parameters:
    
    coll - collection to be checked for containment in this MultiSet.
    
    Returns:
    
    true if this MultiSet contains all of the elements in the specified collection.
    
    Throws:
    
    NullPointerException - if the specified collection contains one or more null elements.
    
    NullPointerException - if the specified collection is null.
    
    See Also:
    
    contains(Object)
  - addAll
```
boolean addAll(MultiSet<? extends T> mvs)
```
    Adds mvs elementwise to this multi set taking multiplicities into account and returns whether this caused a change of the underlying set. **** strange implementation; also: change
    
    Parameters:
    
    mvs - a MultiSet object.
    
    Returns:
    
    returns whether adding changed this MultiSet interpreted as a set.
    
    Throws:
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - addAll
```
boolean addAll(Set<? extends T> set)
```
    Adds set elementwise to this multi set increasing multiplicities and returns whether this caused a change of the underlying set. **** strange implementation; also: change
    
    Parameters:
    
    set - a Set object.
    
    Returns:
    
    returns whether adding changed this MultiSet interpreted as a set.
    
    Throws:
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - removeAll
```
boolean removeAll(Collection<?> coll)
```
    Removes all this MultiSet's elements that are also contained in the specified collection. After this call returns, this MultiSet will contain no elements in common with the specified collection.
    
    Parameters:
    
    coll - elements to be removed from this MultiSet.
    
    Returns:
    
    true if this MultiSet changed as a result of the call.
    
    Throws:
    
    NullPointerException - if the specified collection is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
    
    See Also:
    
    remove(Object), contains(Object)
  - retainAll
```
boolean retainAll(Collection<?> coll)
```
    Retains only the elements in this MultiSet that are contained in the specified collection. In other words, removes from this MultiSet all of its elements that are not contained in the specified collection.
    
    Parameters:
    
    coll - elements to be retained in this MultiSet.
    
    Returns:
    
    true if this MultiSet changed as a result of the call.
    
    Throws:
    
    NullPointerException - if the specified collection is null.
    
    UnsupportedOperationException - if this MultiSet does not support this method.
    
    See Also:
    
    remove(Object), contains(Object)
  - clear
```
void clear()
```
    Removes all of the elements from this MultiSet. This MultiSet will be empty after this method returns.
    
    Throws:
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - getSet
```
Set<T> getSet()
```
    Returns a view of the underlying set of this MultiSet. For certain implementations, this set is immutable to prevent implicit modification of this MultiSet.
    
    Returns:
    
    the Set containing exactly the objects with strictly positive multiplicity in this MultiSet.
  - getMap
```
Map<T,MultiSet.Multiplicity> getMap()
```
    Returns a view of the underlying map of this MultiSet as a map mapping each entry to its multiplicity.
  - getSetWithMults
```
Set<Map.Entry<T,MultiSet.Multiplicity>> getSetWithMults()
```
    Returns a Set view of the mapping from the element of this MultiSet to the according multiplicities. The set is backed by the MultiSet, so changes to the map are reflected in the set, and vice-versa. If the MultiSet is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set may support element removal, which removes the corresponding element from the MultiSet, via the Iterator.remove(), Set.remove(Object), Set.removeAll(Collection), Set.retainAll(Collection) and clear() operations. It does not support the methods add(Object) or Set.addAll(Collection).
  - toString
```
String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
boolean equals(Object obj)
```
    Returns true if and only if obj is also a MultiSet and contains the same elements with the same multiplicities as this one.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - an Object, possibly null.
    
    Returns:
    
    a true if and only if obj is also a MultiSet and contains the same elements with the same multiplicities as this one.
  - hashCode
```
int hashCode()
```
    Overrides:
    
    hashCode in class Object

Interface MultiSet<T>

Nested Class Summary

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

size

sizeWithMult

isEmpty

getObjWithMaxMult

getMaxMult

getMultiplicity

getMultiplicityObj

contains

iterator

toArray

toArray

addWithMult

addWithMult

add

removeWithMult

removeWithMult

remove

setMultiplicity

containsAll

addAll

addAll

removeAll

retainAll

clear

getSet

getMap

getSetWithMults

toString

equals

hashCode