Package eu.simuline.util

Interface MultiSet<T>

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface 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 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()  

    • 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).

      • 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.