Package org.apache.commons.collections4.multiset

# Class AbstractMapMultiSet<E>

java.lang.Object
java.util.AbstractCollection<E>
org.apache.commons.collections4.multiset.AbstractMultiSet<E>
org.apache.commons.collections4.multiset.AbstractMapMultiSet<E>

Type Parameters:
  `E` - the type held in the multiset.

All Implemented Interfaces:
  `Iterable<E>`, `Collection<E>`, `MultiSet<E>`

Direct Known Subclasses:
  `HashMultiSet`

public abstract class AbstractMapMultiSet<E> extends AbstractMultiSet<E>
Abstract implementation of the `MultiSet` interface to simplify the creation of subclass implementations.

Subclasses specify a Map implementation to use as the internal storage. The map will be used to map multiset elements to a number; the number represents the number of occurrences of that element in the multiset.

Since:
  4.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractMapMultiSet.EntrySetIterator<E>`
  Inner class EntrySetIterator.
  `protected static class`
  `AbstractMapMultiSet.MultiSetEntry<E>`
  Inner class MultiSetEntry.
  `protected static class`
  `AbstractMapMultiSet.MutableInteger`
  Mutable integer class for storing the data.
  `protected static class`
  `AbstractMapMultiSet.UniqueSetIterator<E>`
  Inner class UniqueSetIterator.

  ## Nested classes/interfaces inherited from class org.apache.commons.collections4.multiset.AbstractMultiSet

  `AbstractMultiSet.AbstractEntry<E>, AbstractMultiSet.EntrySet<E>, AbstractMultiSet.UniqueSet<E>`

  ## Nested classes/interfaces inherited from interface org.apache.commons.collections4.MultiSet

  `MultiSet.Entry<E>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMapMultiSet()`
  Constructor needed for subclass serialisation.
  `protected`
  `AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map)`
  Constructor that assigns the specified Map as the backing store.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `add(E object, int occurrences)`
  Adds a number of occurrences of the specified object to the MultiSet.
  `void`
  `clear()`
  Clears the multiset by clearing the underlying map.
  `boolean`
  `contains(Object object)`
  Determines if the multiset contains the given element by checking if the underlying map contains the element as a key.
  `protected Iterator<MultiSet.Entry<E>>`
  `createEntrySetIterator()`
  Creates an entry set iterator.
  `protected Iterator<E>`
  `createUniqueSetIterator()`
  Creates a unique set iterator.
  `protected void`
  `doReadObject(ObjectInputStream in)`
  Read the multiset in using a custom routine.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Write the multiset out using a custom routine.
  `boolean`
  `equals(Object object)`
  Compares this MultiSet to another object.
  `int`
  `getCount(Object object)`
  Returns the number of occurrence of the given element in this multiset by looking up its count in the underlying map.
  `protected Map<E,AbstractMapMultiSet.MutableInteger>`
  `getMap()`
  Utility method for implementations to access the map that backs this multiset.
  `int`
  `hashCode()`
  Gets a hash code for the MultiSet compatible with the definition of equals.
  `boolean`
  `isEmpty()`
  Returns true if the underlying map is empty.
  `Iterator<E>`
  `iterator()`
  Gets an iterator over the multiset elements.
  `int`
  `remove(Object object, int occurrences)`
  Removes a number of occurrences of the specified object from the MultiSet.
  `protected void`
  `setMap(Map<E,AbstractMapMultiSet.MutableInteger> map)`
  Sets the map being wrapped.
  `int`
  `size()`
  Returns the number of elements in this multiset.
  `Object[]`
  `toArray()`
  Returns an array of all of this multiset's elements.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array of all of this multiset's elements.
  `protected int`
  `uniqueElements()`
  Returns the number of unique elements in this multiset.

  ### Methods inherited from class org.apache.commons.collections4.multiset.AbstractMultiSet

  `add, createEntrySet, createUniqueSet, entrySet, remove, removeAll, setCount, toString, uniqueSet`

  ### Methods inherited from class java.util.AbstractCollection

  `addAll, containsAll, retainAll`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.util.Collection

  `addAll, parallelStream, removeIf, spliterator, stream`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

  ### Methods inherited from interface org.apache.commons.collections4.MultiSet

  `containsAll, retainAll`

- ## Constructor Details

  - ### AbstractMapMultiSet

    protected AbstractMapMultiSet()
    Constructor needed for subclass serialisation.

  - ### AbstractMapMultiSet

    protected AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map)
    Constructor that assigns the specified Map as the backing store. The map must be empty and non-null.
    Parameters:
      `map` - the map to assign

- ## Method Details

  - ### add

    public int add(E object, int occurrences)
    Description copied from interface: `MultiSet`
    Adds a number of occurrences of the specified object to the MultiSet.

    If the object is already in the `MultiSet.uniqueSet()` then increment its count as reported by `MultiSet.getCount(Object)`. Otherwise, add it to the `MultiSet.uniqueSet()` and report its count as `occurrences`.

    Specified by:
      `add` in interface `MultiSet<E>`
    Overrides:
      `add` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - the object to add
      `occurrences` - the number of occurrences to add, may be zero, in which case no change is made to the multiset
    Returns:
      the number of occurrences of the object in the multiset before this operation; possibly zero

  - ### clear

    public void clear()
    Clears the multiset by clearing the underlying map.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractMultiSet<E>`

  - ### contains

    public boolean contains(Object object)
    Determines if the multiset contains the given element by checking if the underlying map contains the element as a key.
    Specified by:
      `contains` in interface `Collection<E>`
    Overrides:
      `contains` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - the object to search for
    Returns:
      true if the multiset contains the given element

  - ### createEntrySetIterator

    protected Iterator<MultiSet.Entry<E>> createEntrySetIterator()
    Description copied from class: `AbstractMultiSet`
    Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
    Specified by:
      `createEntrySetIterator` in class `AbstractMultiSet<E>`
    Returns:
      the entrySet iterator

  - ### createUniqueSetIterator

    protected Iterator<E> createUniqueSetIterator()
    Description copied from class: `AbstractMultiSet`
    Creates a unique set iterator. Subclasses can override this to return iterators with different properties.
    Overrides:
      `createUniqueSetIterator` in class `AbstractMultiSet<E>`
    Returns:
      the uniqueSet iterator

  - ### doReadObject

    protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
    Read the multiset in using a custom routine.
    Overrides:
      `doReadObject` in class `AbstractMultiSet<E>`
    Parameters:
      `in` - the input stream
    Throws:
      `IOException` - any of the usual I/O related exceptions
      `ClassNotFoundException` - if the stream contains an object which class cannot be loaded
      `ClassCastException` - if the stream does not contain the correct objects

  - ### doWriteObject

    protected void doWriteObject(ObjectOutputStream out) throws IOException
    Write the multiset out using a custom routine.
    Overrides:
      `doWriteObject` in class `AbstractMultiSet<E>`
    Parameters:
      `out` - the output stream
    Throws:
      `IOException` - any of the usual I/O related exceptions

  - ### equals

    public boolean equals(Object object)
    Description copied from interface: `MultiSet`
    Compares this MultiSet to another object.

    This MultiSet equals another object if it is also a MultiSet that contains the same number of occurrences of the same elements.

    Specified by:
      `equals` in interface `Collection<E>`
    Specified by:
      `equals` in interface `MultiSet<E>`
    Overrides:
      `equals` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - the object to compare to
    Returns:
      true if equal

  - ### getCount

    public int getCount(Object object)
    Returns the number of occurrence of the given element in this multiset by looking up its count in the underlying map.
    Specified by:
      `getCount` in interface `MultiSet<E>`
    Overrides:
      `getCount` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - the object to search for
    Returns:
      the number of occurrences of the object, zero if not found

  - ### getMap

    protected Map<E,AbstractMapMultiSet.MutableInteger> getMap()
    Utility method for implementations to access the map that backs this multiset. Not intended for interactive use outside of subclasses.
    Returns:
      the map being used by the MultiSet

  - ### hashCode

    public int hashCode()
    Description copied from interface: `MultiSet`
    Gets a hash code for the MultiSet compatible with the definition of equals. The hash code is defined as the sum total of a hash code for each element. The per element hash code is defined as `(e==null ? 0 : e.hashCode()) ^ noOccurrences)`.
    Specified by:
      `hashCode` in interface `Collection<E>`
    Specified by:
      `hashCode` in interface `MultiSet<E>`
    Overrides:
      `hashCode` in class `AbstractMultiSet<E>`
    Returns:
      the hash code of the MultiSet

  - ### isEmpty

    public boolean isEmpty()
    Returns true if the underlying map is empty.
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:
      true if multiset is empty

  - ### iterator

    public Iterator<E> iterator()
    Gets an iterator over the multiset elements. Elements present in the MultiSet more than once will be returned repeatedly.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in interface `MultiSet<E>`
    Overrides:
      `iterator` in class `AbstractMultiSet<E>`
    Returns:
      the iterator

  - ### remove

    public int remove(Object object, int occurrences)
    Description copied from interface: `MultiSet`
    Removes a number of occurrences of the specified object from the MultiSet.

    If the number of occurrences to remove is greater than the actual number of occurrences in the multiset, the object will be removed from the multiset.

    Specified by:
      `remove` in interface `MultiSet<E>`
    Overrides:
      `remove` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - the object to remove
      `occurrences` - the number of occurrences to remove, may be zero, in which case no change is made to the multiset
    Returns:
      the number of occurrences of the object in the multiset before the operation; possibly zero

  - ### setMap

    protected void setMap(Map<E,AbstractMapMultiSet.MutableInteger> map)
    Sets the map being wrapped.

    Note: this method should only be used during deserialization

    Parameters:
      `map` - the map to wrap

  - ### size

    public int size()
    Returns the number of elements in this multiset.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in interface `MultiSet<E>`
    Overrides:
      `size` in class `AbstractMultiSet<E>`
    Returns:
      current size of the multiset

  - ### toArray

    public Object[] toArray()
    Returns an array of all of this multiset's elements.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Returns:
      an array of all of this multiset's elements

  - ### toArray

    public <T> T[] toArray(T[] array)
    Returns an array of all of this multiset's elements. If the input array has more elements than are in the multiset, trailing elements will be set to null.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Type Parameters:
      `T` - the type of the array elements
    Parameters:
      `array` - the array to populate
    Returns:
      an array of all of this multiset's elements
    Throws:
      `ArrayStoreException` - if the runtime type of the specified array is not a supertype of the runtime type of the elements in this list
      `NullPointerException` - if the specified array is null

  - ### uniqueElements

    protected int uniqueElements()
    Description copied from class: `AbstractMultiSet`
    Returns the number of unique elements in this multiset.
    Specified by:
      `uniqueElements` in class `AbstractMultiSet<E>`
    Returns:
      the number of unique elements