Package org.apache.commons.collections4.bag

# Class AbstractMapBag<E>

java.lang.Object
org.apache.commons.collections4.bag.AbstractMapBag<E>

Type Parameters:
  `E` - the type of elements in this bag

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

Direct Known Subclasses:
  `HashBag`, `TreeBag`

public abstract class AbstractMapBag<E> extends Object implements Bag<E>
Abstract implementation of the `Bag` 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 bag elements to a number; the number represents the number of occurrences of that element in the bag.

Since:
  3.0 (previously DefaultMapBag v2.0)

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractMapBag.MutableInteger`
  Mutable integer class for storing the data.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMapBag()`
  Constructor needed for subclass serialisation.
  `protected`
  `AbstractMapBag(Map<E,AbstractMapBag.MutableInteger> map)`
  Constructor that assigns the specified Map as the backing store.
  `protected`
  `AbstractMapBag(Map<E,AbstractMapBag.MutableInteger> map, Iterable<? extends E> iterable)`
  Constructs a new instance that assigns the specified Map as the backing store.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Adds a new element to the bag, incrementing its count in the underlying map.
  `boolean`
  `add(E object, int nCopies)`
  Adds a new element to the bag, incrementing its count in the map.
  `boolean`
  `addAll(Collection<? extends E> coll)`
  Invokes `add(Object)` for each element in the given collection.
  `void`
  `clear()`
  Clears the bag by clearing the underlying map.
  `boolean`
  `contains(Object object)`
  Determines if the bag contains the given element by checking if the underlying map contains the element as a key.
  `boolean`
  `containsAll(Collection<?> coll)`
  Determines if the bag contains the given elements.
  `protected void`
  `doReadObject(Map<E,AbstractMapBag.MutableInteger> map, ObjectInputStream in)`
  Read the map in using a custom routine.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Write the map out using a custom routine.
  `boolean`
  `equals(Object object)`
  Compares this Bag to another.
  `int`
  `getCount(Object object)`
  Returns the number of occurrence of the given element in this bag by looking up its count in the underlying map.
  `protected Map<E,AbstractMapBag.MutableInteger>`
  `getMap()`
  Utility method for implementations to access the map that backs this bag.
  `int`
  `hashCode()`
  Gets a hash code for the Bag compatible with the definition of equals.
  `boolean`
  `isEmpty()`
  Returns true if the underlying map is empty.
  `Iterator<E>`
  `iterator()`
  Gets an iterator over the bag elements.
  `boolean`
  `remove(Object object)`
  Removes all copies of the specified object from the bag.
  `boolean`
  `remove(Object object, int nCopies)`
  Removes a specified number of copies of an object from the bag.
  `boolean`
  `removeAll(Collection<?> coll)`
  Removes objects from the bag according to their count in the specified collection.
  `boolean`
  `retainAll(Collection<?> coll)`
  Remove any members of the bag that are not in the given bag, respecting cardinality.
  `int`
  `size()`
  Returns the number of elements in this bag.
  `Object[]`
  `toArray()`
  Returns an array of all of this bag's elements.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array of all of this bag's elements.
  `String`
  `toString()`
  Implement a toString() method suitable for debugging.
  `Set<E>`
  `uniqueSet()`
  Returns an unmodifiable view of the underlying map's key set.

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

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

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

  `parallelStream, removeIf, spliterator, stream`

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

  `forEach`

- ## Constructor Details

  - ### AbstractMapBag

    protected AbstractMapBag()
    Constructor needed for subclass serialisation.

  - ### AbstractMapBag

    protected AbstractMapBag(Map<E,AbstractMapBag.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

  - ### AbstractMapBag

    protected AbstractMapBag(Map<E,AbstractMapBag.MutableInteger> map, Iterable<? extends E> iterable)
    Constructs a new instance that assigns the specified Map as the backing store. The map must be empty and non-null. The bag is filled from the iterable elements.
    Parameters:
      `map` - the map to assign.
      `iterable` - The bag is filled from these iterable elements.

- ## Method Details

  - ### add

    public boolean add(E object)
    Adds a new element to the bag, incrementing its count in the underlying map.
    Specified by:
      `add` in interface `Bag<E>`
    Specified by:
      `add` in interface `Collection<E>`
    Parameters:
      `object` - the object to add
    Returns:
      `true` if the object was not already in the `uniqueSet`

  - ### add

    public boolean add(E object, int nCopies)
    Adds a new element to the bag, incrementing its count in the map.
    Specified by:
      `add` in interface `Bag<E>`
    Parameters:
      `object` - the object to search for
      `nCopies` - the number of copies to add
    Returns:
      `true` if the object was not already in the `uniqueSet`

  - ### addAll

    public boolean addAll(Collection<? extends E> coll)
    Invokes `add(Object)` for each element in the given collection.
    Specified by:
      `addAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to add
    Returns:
      `true` if this call changed the bag

  - ### clear

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

  - ### contains

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

  - ### containsAll

    public boolean containsAll(Collection<?> coll)
    Determines if the bag contains the given elements.
    Specified by:
      `containsAll` in interface `Bag<E>`
    Specified by:
      `containsAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to check against
    Returns:
      `true` if the Bag contains all the collection

  - ### doReadObject

    protected void doReadObject(Map<E,AbstractMapBag.MutableInteger> map, ObjectInputStream in) throws IOException, ClassNotFoundException
    Read the map in using a custom routine.
    Parameters:
      `map` - the map to use
      `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 map out using a custom routine.
    Parameters:
      `out` - the output stream
    Throws:
      `IOException` - any of the usual I/O related exceptions

  - ### equals

    public boolean equals(Object object)
    Compares this Bag to another. This Bag equals another Bag if it contains the same number of occurrences of the same elements.
    Specified by:
      `equals` in interface `Collection<E>`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the Bag to compare to
    Returns:
      true if equal

  - ### getCount

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

  - ### getMap

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

  - ### hashCode

    public int hashCode()
    Gets a hash code for the Bag 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)`. This hash code is compatible with the Set interface.
    Specified by:
      `hashCode` in interface `Collection<E>`
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code of the Bag

  - ### isEmpty

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

  - ### iterator

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

  - ### remove

    public boolean remove(Object object)
    Removes all copies of the specified object from the bag.
    Specified by:
      `remove` in interface `Bag<E>`
    Specified by:
      `remove` in interface `Collection<E>`
    Parameters:
      `object` - the object to remove
    Returns:
      true if the bag changed

  - ### remove

    public boolean remove(Object object, int nCopies)
    Removes a specified number of copies of an object from the bag.
    Specified by:
      `remove` in interface `Bag<E>`
    Parameters:
      `object` - the object to remove
      `nCopies` - the number of copies to remove
    Returns:
      true if the bag changed

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    Removes objects from the bag according to their count in the specified collection.
    Specified by:
      `removeAll` in interface `Bag<E>`
    Specified by:
      `removeAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to use
    Returns:
      true if the bag changed

  - ### retainAll

    public boolean retainAll(Collection<?> coll)
    Remove any members of the bag that are not in the given bag, respecting cardinality.
    Specified by:
      `retainAll` in interface `Bag<E>`
    Specified by:
      `retainAll` in interface `Collection<E>`
    Parameters:
      `coll` - the collection to retain
    Returns:
      true if this call changed the collection

  - ### size

    public int size()
    Returns the number of elements in this bag.
    Specified by:
      `size` in interface `Bag<E>`
    Specified by:
      `size` in interface `Collection<E>`
    Returns:
      current size of the bag

  - ### toArray

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

  - ### toArray

    public <T> T[] toArray(T[] array)
    Returns an array of all of this bag's elements. If the input array has more elements than are in the bag, trailing elements will be set to null.
    Specified by:
      `toArray` in interface `Collection<E>`
    Type Parameters:
      `T` - the type of the array elements
    Parameters:
      `array` - the array to populate
    Returns:
      an array of all of this bag'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

  - ### toString

    public String toString()
    Implement a toString() method suitable for debugging.
    Overrides:
      `toString` in class `Object`
    Returns:
      a debugging toString

  - ### uniqueSet

    public Set<E> uniqueSet()
    Returns an unmodifiable view of the underlying map's key set.
    Specified by:
      `uniqueSet` in interface `Bag<E>`
    Returns:
      the set of unique elements in this bag