Package org.apache.commons.collections4.bag

Class 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)

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      (package private) boolean containsAll​(Bag<?> other)
      Returns true if the bag contains all elements in the given collection, respecting cardinality.
      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.
      (package private) boolean retainAll​(Bag<?> other)
      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.

    • Constructor Detail

      • 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

    • Method Detail

      • 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

      • 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

      • 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

      • 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

      • 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

      • containsAll

        boolean containsAll​(Bag<?> other)
        Returns true if the bag contains all elements in the given collection, respecting cardinality.
        Parameters:
        other - the bag to check against
        Returns:
        true if the Bag contains all the collection

      • 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

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

      • 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

      • retainAll

        boolean retainAll​(Bag<?> other)
        Remove any members of the bag that are not in the given bag, respecting cardinality.
        Parameters:
        other - the bag to retain
        Returns:
        true if this call changed the collection
        See Also:
        retainAll(Collection)

      • 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

      • 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

      • 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

      • 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()) ^ noOccurances). 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

      • toString

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