Package org.apache.commons.collections4.bag

# Class CollectionSortedBag<E>

java.lang.Object
org.apache.commons.collections4.collection.AbstractCollectionDecorator<E>
org.apache.commons.collections4.bag.AbstractBagDecorator<E>
org.apache.commons.collections4.bag.AbstractSortedBagDecorator<E>
org.apache.commons.collections4.bag.CollectionSortedBag<E>

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

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

public final class CollectionSortedBag<E> extends AbstractSortedBagDecorator<E>
Decorates another `SortedBag` to comply with the Collection contract.

Since:
  4.0
See Also:
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CollectionSortedBag(SortedBag<E> bag)`
  Constructor that wraps (not copies).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  (Violation) Adds one copy of the specified object to the Bag.
  `boolean`
  `add(E object, int count)`
  Adds `nCopies` copies of the specified object to the Bag.
  `boolean`
  `addAll(Collection<? extends E> coll)`
  `static <E> SortedBag<E>`
  `collectionSortedBag(SortedBag<E> bag)`
  Factory method to create a sorted bag that complies to the Collection contract.
  `boolean`
  `containsAll(Collection<?> coll)`
  (Violation) Returns `true` if the bag contains all elements in the given collection, respecting cardinality.
  `boolean`
  `remove(Object object)`
  (Violation) Removes all occurrences of the given object from the bag.
  `boolean`
  `removeAll(Collection<?> coll)`
  (Violation) Remove all elements represented in the given collection, respecting cardinality.
  `boolean`
  `retainAll(Collection<?> coll)`
  (Violation) Remove any members of the bag that are not in the given collection, respecting cardinality.

  ### Methods inherited from class org.apache.commons.collections4.bag.AbstractSortedBagDecorator

  `comparator, decorated, first, last`

  ### Methods inherited from class org.apache.commons.collections4.bag.AbstractBagDecorator

  `equals, getCount, hashCode, remove, uniqueSet`

  ### Methods inherited from class org.apache.commons.collections4.collection.AbstractCollectionDecorator

  `clear, contains, isEmpty, iterator, removeIf, setCollection, size, toArray, toArray, toString`

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

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

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

  `getCount, iterator, remove, size, uniqueSet`

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

  `clear, contains, equals, hashCode, isEmpty, parallelStream, removeIf, spliterator, stream, toArray, toArray`

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

  `forEach`

- ## Constructor Details

  - ### CollectionSortedBag

    public CollectionSortedBag(SortedBag<E> bag)
    Constructor that wraps (not copies).
    Parameters:
      `bag` - the sorted bag to decorate, must not be null
    Throws:
      `NullPointerException` - if bag is null

- ## Method Details

  - ### collectionSortedBag

    public static <E> SortedBag<E> collectionSortedBag(SortedBag<E> bag)
    Factory method to create a sorted bag that complies to the Collection contract.
    Type Parameters:
      `E` - the type of the elements in the bag
    Parameters:
      `bag` - the sorted bag to decorate, must not be null
    Returns:
      a SortedBag that complies to the Collection contract
    Throws:
      `NullPointerException` - if bag is null

  - ### add

    public boolean add(E object)
    Description copied from interface: `Bag`
    (Violation) Adds one copy of the specified object to the Bag.

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

    Since this method always increases the size of the bag, according to the `Collection.add(Object)` contract, it should always return `true`. Since it sometimes returns `false`, this method violates the contract.

    Specified by:
      `add` in interface `Bag<E>`
    Specified by:
      `add` in interface `Collection<E>`
    Overrides:
      `add` in class `AbstractCollectionDecorator<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 count)
    Description copied from interface: `Bag`
    Adds `nCopies` copies of the specified object to the Bag.

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

    Specified by:
      `add` in interface `Bag<E>`
    Overrides:
      `add` in class `AbstractBagDecorator<E>`
    Parameters:
      `object` - the object to add
      `count` - 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)
    Specified by:
      `addAll` in interface `Collection<E>`
    Overrides:
      `addAll` in class `AbstractCollectionDecorator<E>`

  - ### containsAll

    public boolean containsAll(Collection<?> coll)
    Description copied from interface: `Bag`
    (Violation) Returns `true` if the bag contains all elements in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object, calling `Bag.getCount(Object)` on that object must be `&gt;= n` for all `n` in `coll`.

    The `Collection.containsAll(Collection)` method specifies that cardinality should not be respected; this method should return true if the bag contains at least one of every object contained in the given collection.

    Specified by:
      `containsAll` in interface `Bag<E>`
    Specified by:
      `containsAll` in interface `Collection<E>`
    Overrides:
      `containsAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to check against
    Returns:
      `true` if the Bag contains all the collection

  - ### remove

    public boolean remove(Object object)
    Description copied from interface: `Bag`
    (Violation) Removes all occurrences of the given object from the bag.

    This will also remove the object from the `Bag.uniqueSet()`.

    According to the `Collection.remove(Object)` method, this method should only remove the first occurrence of the given object, not all occurrences.

    Specified by:
      `remove` in interface `Bag<E>`
    Specified by:
      `remove` in interface `Collection<E>`
    Overrides:
      `remove` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `object` - the object to remove
    Returns:
      `true` if this call changed the collection

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    Description copied from interface: `Bag`
    (Violation) Remove all elements represented in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object, the bag will have `n` fewer copies, assuming the bag had at least `n` copies to begin with.

    The `Collection.removeAll(Collection)` method specifies that cardinality should not be respected; this method should remove all occurrences of every object contained in the given collection.

    Specified by:
      `removeAll` in interface `Bag<E>`
    Specified by:
      `removeAll` in interface `Collection<E>`
    Overrides:
      `removeAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to remove
    Returns:
      `true` if this call changed the collection

  - ### retainAll

    public boolean retainAll(Collection<?> coll)
    Description copied from interface: `Bag`
    (Violation) Remove any members of the bag that are not in the given collection, respecting cardinality. That is, if the given collection `coll` contains `n` copies of a given object and the bag has `m &gt; n` copies, then delete `m - n` copies from the bag. In addition, if `e` is an object in the bag but `!coll.contains(e)`, then remove `e` and any of its copies.

    The `Collection.retainAll(Collection)` method specifies that cardinality should not be respected; this method should keep all occurrences of every object contained in the given collection.

    Specified by:
      `retainAll` in interface `Bag<E>`
    Specified by:
      `retainAll` in interface `Collection<E>`
    Overrides:
      `retainAll` in class `AbstractCollectionDecorator<E>`
    Parameters:
      `coll` - the collection to retain
    Returns:
      `true` if this call changed the collection