AbstractMultiSet (TestHelpers 1.0-SNAPSHOT API)

java.lang.Object
- eu.simuline.util.AbstractMultiSet<MAP,T>

Type Parameters:

MAP - the map assigning to each element of this multi-set its multiplicity.

T - the class of the elements of this multi-set. Created: Sun Nov 23 23:32:06 2014

All Implemented Interfaces:

MultiSet<T>, Iterable<T>

Direct Known Subclasses:

HashMultiSet, TreeMultiSet
```
public abstract class AbstractMultiSet<MAP extends Map<T,MultiSet.Multiplicity>,T>
extends Object
implements MultiSet<T>
```
Represents an abstract MultiSet based on a Map.
addAll's implementation seems strange, add seems to be buggy, Problem with overflow of multiplicities.

Version:

1.0

Author:

Ernst Reissner

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`AbstractMultiSet.MultiplicityImpl` Serves as a wrapper object for a multiplicity `AbstractMultiSet.MultiplicityImpl.mult`.
`protected static class`	`AbstractMultiSet.MultiSetIteratorImpl<T>` A canonical implementation of `MultiSetIterator` defining also the methods modifying the underlying `MultiSet`, namely `AbstractMultiSet.MultiSetIteratorImpl.remove()`, `AbstractMultiSet.MultiSetIteratorImpl.setMult(int)` and `AbstractMultiSet.MultiSetIteratorImpl.removeMult(int)`.

Nested classes/interfaces inherited from interface eu.simuline.util.MultiSet
MultiSet.Multiplicity

Field Summary

Fields
Modifier and Type Field and Description

protected MAP obj2mult
Maps objects to its multiplicities.

Fields
Modifier and Type	Field and Description
`protected MAP`	`obj2mult` Maps objects to its multiplicities.

Constructor Summary

Constructors
Constructor and Description

AbstractMultiSet(MAP t2mult)

Constructors
Constructor and Description
`AbstractMultiSet(MAP t2mult)`

Method Summary

All Methods Instance Methods Concrete 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 increasing multiplicities 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.
`int`	`getMaxMult()` Returns the maximal multiplicity of an element in this set.
`private Map.Entry<T,MultiSet.Multiplicity>`	`getMaxObjWithMult()` Returns a Map.Entry representing an element in this `MultiSet` with maximal multiplicity together with this multiplicity, except if this set is empty.
`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`.
`T`	`getObjWithMaxMult()` Returns one of the elements in this multiple set with maximal multiplicity.
`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.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface eu.simuline.util.MultiSet
getMap, getSet, toString

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

- Field Detail
  - obj2mult
```
protected final MAP extends Map<T,MultiSet.Multiplicity> obj2mult
```
    Maps objects to its multiplicities. The keys are objects whereas the corresponding values are strictly positive Integers representing the corresponding multiplicities. If an object is not within this set, the corresponding value is null. **** maybe even: object not in keyset. In the key set no null values may occur.
- Constructor Detail
  - AbstractMultiSet
```
public AbstractMultiSet(MAP t2mult)
```
- Method Detail
  - size
```
public final 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.
    
    Specified by:
    
    size in interface MultiSet<T>
    
    Returns:
    
    the number of elements in this MultiSet each multiple element counted as a single one.
    
    See Also:
    
    sizeWithMult()
  - sizeWithMult
```
public final 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.
    
    Specified by:
    
    sizeWithMult in interface MultiSet<T>
    
    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
```
public final boolean isEmpty()
```
    Returns whether this multiple set contains no element.
    
    Specified by:
    
    isEmpty in interface MultiSet<T>
    
    Returns:
    
    whether this multiple set contains no element.
  - getMaxObjWithMult
```
private Map.Entry<T,MultiSet.Multiplicity> getMaxObjWithMult()
```
    Returns a Map.Entry representing an element in this MultiSet with maximal multiplicity together with this multiplicity, except if this set is empty. For empty sets, null is returned.
    Returns:
    if this MultiSet is not empty, a Map.Entry object em is returned: em.getKey() is an element of this MultiSet and em.getValue() is a Multiplicity wrapping its multiplicity m = em.getValue().get(). This multiplicity is maximal but if there is more than one such maximal multiplicity, it is not specified which Map.Entry is returned.
    Note that em.getKey() may never be null
    if this MultiSet is empty, null is returned.
    See Also:
    
    getObjWithMaxMult(), getMaxMult()
  - getObjWithMaxMult
```
public final T 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.
    
    Specified by:
    
    getObjWithMaxMult in interface MultiSet<T>
    
    Returns:
    
    a Object o != null with maximal multiplicity or null if this multiple set is empty.
    
    See Also:
    
    isEmpty()
  - getMaxMult
```
public final int getMaxMult()
```
    Returns the maximal multiplicity of an element in this set. In particular for empty sets returns 0.
    
    Specified by:
    
    getMaxMult in interface MultiSet<T>
    
    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
```
public final int getMultiplicity(Object obj)
```
    Returns the multiplicity with which the given object occurs within this set.
    
    Specified by:
    
    getMultiplicity in interface MultiSet<T>
    
    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
```
public final MultiSet.Multiplicity getMultiplicityObj(Object obj)
```
    Returns the multiplicity object of the given object in this set or null.
    
    Specified by:
    
    getMultiplicityObj in interface MultiSet<T>
    
    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
```
public final 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)).
    
    Specified by:
    
    contains in interface MultiSet<T>
    
    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
```
public final 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 MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    toArray in interface MultiSet<T>
    
    Returns:
    
    an array containing all of the elements in this collection
    
    See Also:
    
    iterator()
  - toArray
```
public final 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().
    Specified by:
    
    toArray in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    addWithMult in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    addWithMult in interface MultiSet<T>
    
    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
```
public final 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).
    
    Specified by:
    
    add in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    removeWithMult in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    removeWithMult in interface MultiSet<T>
    
    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
```
public final 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).
    
    Specified by:
    
    remove in interface MultiSet<T>
    
    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
```
public final int setMultiplicity(T obj,
                                 int newMult)
```
    Sets the multiplicity of obj to the value specified by mult.
    
    Specified by:
    
    setMultiplicity in interface MultiSet<T>
    
    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
```
public final boolean containsAll(Collection<?> coll)
```
    Returns true if this MultiSet contains all of the elements in the specified collection with strictly positive multiplicity.
    
    Specified by:
    
    containsAll in interface MultiSet<T>
    
    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
```
public final boolean addAll(MultiSet<? extends T> mvs)
```
    Adds mvs elementwise to this multi set increasing multiplicities and returns whether this caused a change of the underlying set. **** strange implementation; also: change
    
    Specified by:
    
    addAll in interface MultiSet<T>
    
    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
```
public final 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
    
    Specified by:
    
    addAll in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    removeAll in interface MultiSet<T>
    
    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
```
public final 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.
    
    Specified by:
    
    retainAll in interface MultiSet<T>
    
    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
```
public final void clear()
```
    Removes all of the elements from this MultiSet. This MultiSet will be empty after this method returns.
    
    Specified by:
    
    clear in interface MultiSet<T>
    
    Throws:
    
    UnsupportedOperationException - if this MultiSet does not support this method.
  - getSetWithMults
```
public final 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).
    
    Specified by:
    
    getSetWithMults in interface MultiSet<T>
  - equals
```
public final 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.
    
    Specified by:
    
    equals in interface MultiSet<T>
    
    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
```
public final int hashCode()
```
    Specified by:
    
    hashCode in interface MultiSet<T>
    
    Overrides:
    
    hashCode in class Object

Class AbstractMultiSet<MAP extends Map<T,MultiSet.Multiplicity>,T>

Nested Class Summary

Nested classes/interfaces inherited from interface eu.simuline.util.MultiSet

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface eu.simuline.util.MultiSet

Methods inherited from interface java.lang.Iterable

Field Detail

obj2mult

Constructor Detail

AbstractMultiSet

Method Detail

size

sizeWithMult

isEmpty

getMaxObjWithMult

getObjWithMaxMult

getMaxMult

getMultiplicity

getMultiplicityObj

contains

iterator

toArray

toArray

addWithMult

addWithMult

add

removeWithMult

removeWithMult

remove

setMultiplicity

containsAll

addAll

addAll

removeAll

retainAll

clear

getSetWithMults

equals

hashCode