Package eu.simuline.util

Class AbstractMultiSet<MAP extends java.util.Map<T,​MultiSet.Multiplicity>,​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>, java.lang.Iterable<T>
    Direct Known Subclasses:
    HashMultiSet, TreeMultiSet
    public abstract class AbstractMultiSet<MAP extends java.util.Map<T,​MultiSet.Multiplicity>,​T>
extends java.lang.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

    • Field Summary

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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​(java.util.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​(java.lang.Object obj)
      Returns true if this MultiSet contains the specified element.
      boolean containsAll​(java.util.Collection<?> coll)
      Returns true if this MultiSet contains all of the elements in the specified collection with strictly positive multiplicity.
      boolean equals​(java.lang.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 java.util.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​(java.lang.Object obj)
      Returns the multiplicity with which the given object occurs within this set.
      MultiSet.Multiplicity getMultiplicityObj​(java.lang.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.
      java.util.Set<java.util.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​(java.lang.Object obj)
      Removes all instances of the specified element from this MultiSet, if it is present with nontrivial multiplicity.
      boolean removeAll​(java.util.Collection<?> coll)
      Removes all this MultiSet's elements that are also contained in the specified collection.
      int removeWithMult​(java.lang.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​(java.lang.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​(java.util.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.
      java.lang.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 java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • obj2mult

        protected final MAP extends java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Returns:
        whether this multiple set contains no element.

      • getMaxObjWithMult

        private java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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​(java.lang.Object obj)
        Returns the multiplicity with which the given object occurs within this set.
        Specified by:
        getMultiplicity in interface MultiSet<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.NullPointerException - for obj==null.
        See Also:
        setMultiplicity(Object, int), getMultiplicityObj(Object)

      • getMultiplicityObj

        public final MultiSet.Multiplicity getMultiplicityObj​(java.lang.Object obj)
        Returns the multiplicity object of the given object in this set or null.
        Specified by:
        getMultiplicityObj in interface MultiSet<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.NullPointerException - for obj==null.
        See Also:
        getMultiplicity(Object)

      • contains

        public final boolean contains​(java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        obj - element (not null) whose presence in this MultiSet is to be tested.
        Returns:
        true if this MultiSet contains the specified element.
        Throws:
        java.lang.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 java.lang.Iterable<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Specified by:
        iterator in interface MultiSet<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Returns:
        an Iterator over the elements in this collection considering each element exactly once ignoring its multiplicity.

      • toArray

        public final java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.ArrayStoreException - the runtime type of the specified array is not a supertype of the runtime type of every element in this MultiSet.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        obj - a Object. Note that this object may not be null.
        Returns:
        a strictly positive int value: the new multiplicity of obj.
        Throws:
        java.lang.NullPointerException - if the specified element is null.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.IllegalArgumentException - for addMult < 0.
        java.lang.NullPointerException - for obj==null provided addMult ≥ 0.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.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:
        java.lang.NullPointerException - if the specified element is null.
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • removeWithMult

        public final int removeWithMult​(java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.NullPointerException - if the specified element is null.
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • removeWithMult

        public final int removeWithMult​(java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.NullPointerException - for obj == null.
        java.lang.IllegalArgumentException - for removeMult < 0 and also if removeMult - obj.getMultiplicity() < 0.
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • remove

        public final boolean remove​(java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        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:
        java.lang.NullPointerException - if the specified element is null.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        obj - an Object instance.
        newMult - a non-negative int value.
        Returns:
        the old multiplicity of obj as a non-negative int value.
        Throws:
        java.lang.IllegalArgumentException - if either obj == null or mult ≤ 0.
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.
        See Also:
        getMultiplicity(Object)

      • containsAll

        public final boolean containsAll​(java.util.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<MAP extends java.util.Map<T,​MultiSet.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:
        java.lang.NullPointerException - if the specified collection contains one or more null elements.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        mvs - a MultiSet object.
        Returns:
        returns whether adding changed this MultiSet interpreted as a set.
        Throws:
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • addAll

        public final boolean addAll​(java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        set - a Set object.
        Returns:
        returns whether adding changed this MultiSet interpreted as a set.
        Throws:
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • removeAll

        public final boolean removeAll​(java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        coll - elements to be removed from this MultiSet.
        Returns:
        true if this MultiSet changed as a result of the call.
        Throws:
        java.lang.NullPointerException - if the specified collection is null.
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.
        See Also:
        remove(Object), contains(Object)

      • retainAll

        public final boolean retainAll​(java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Parameters:
        coll - elements to be retained in this MultiSet.
        Returns:
        true if this MultiSet changed as a result of the call.
        Throws:
        java.lang.NullPointerException - if the specified collection is null.
        java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Throws:
        java.lang.UnsupportedOperationException - if this MultiSet does not support this method.

      • getSetWithMults

        public final java.util.Set<java.util.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>

      • equals

        public final boolean equals​(java.lang.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<MAP extends java.util.Map<T,​MultiSet.Multiplicity>>
        Overrides:
        equals in class java.lang.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.