Package org.apache.commons.collections4.bag

# Class TreeBag<E>

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

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

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

public class TreeBag<E> extends AbstractMapBag<E> implements SortedBag<E>, Serializable
Implements `SortedBag`, using a `TreeMap` to provide the data storage. This is the standard implementation of a sorted bag.

Order will be maintained among the bag members and can be viewed through the iterator.

A `Bag` stores each object in the collection together with a count of occurrences. Extra methods on the interface allow multiple copies of an object to be added or removed at once. It is important to read the interface Javadoc carefully as several methods violate the `Collection` interface specification.

Since:
  3.0 (previously in main package v2.0)
See Also:
  - Serialized Form

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.commons.collections4.bag.AbstractMapBag

  `AbstractMapBag.MutableInteger`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TreeBag()`
  Constructs an empty `TreeBag`.
  `TreeBag(Iterable<? extends E> iterable)`
  Constructs a bag containing all the members of the given Iterable.
  `TreeBag(Collection<? extends E> coll)`
  Constructs a `TreeBag` containing all the members of the specified collection.
  `TreeBag(Comparator<? super E> comparator)`
  Constructs an empty bag that maintains order on its unique representative members according to the given `Comparator`.

- ## 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.
  `Comparator<? super E>`
  `comparator()`
  Returns the comparator associated with this sorted set, or null if it uses its elements' natural ordering.
  `E`
  `first()`
  Returns the first (lowest) member.
  `protected SortedMap<E,AbstractMapBag.MutableInteger>`
  `getMap()`
  Utility method for implementations to access the map that backs this bag.
  `E`
  `last()`
  Returns the last (highest) member.

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

  `add, addAll, clear, contains, containsAll, doReadObject, doWriteObject, equals, getCount, hashCode, isEmpty, iterator, remove, remove, removeAll, retainAll, size, toArray, toArray, toString, uniqueSet`

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

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

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

  `add, containsAll, getCount, iterator, remove, remove, removeAll, retainAll, size, uniqueSet`

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

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

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

  `forEach`

- ## Constructor Details

  - ### TreeBag

    public TreeBag()
    Constructs an empty `TreeBag`.

  - ### TreeBag

    public TreeBag(Collection<? extends E> coll)
    Constructs a `TreeBag` containing all the members of the specified collection.
    Parameters:
      `coll` - the collection to copy into the bag

  - ### TreeBag

    public TreeBag(Comparator<? super E> comparator)
    Constructs an empty bag that maintains order on its unique representative members according to the given `Comparator`.
    Parameters:
      `comparator` - the comparator to use

  - ### TreeBag

    public TreeBag(Iterable<? extends E> iterable)
    Constructs a bag containing all the members of the given Iterable.
    Parameters:
      `iterable` - an iterable to copy into this bag.
    Since:
      4.5.0-M3

- ## 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>`
    Overrides:
      `add` in class `AbstractMapBag<E>`
    Parameters:
      `object` - the object to add
    Returns:
      `true` if the object was not already in the `uniqueSet`
    Throws:
      `IllegalArgumentException` - if the object to be added does not implement `Comparable` and the `TreeBag` is using natural ordering
      `NullPointerException` - if the specified key is null and this bag uses natural ordering, or its comparator does not permit null keys

  - ### comparator

    public Comparator<? super E> comparator()
    Description copied from interface: `SortedBag`
    Returns the comparator associated with this sorted set, or null if it uses its elements' natural ordering.
    Specified by:
      `comparator` in interface `SortedBag<E>`
    Returns:
      the comparator in use, or null if natural ordering

  - ### first

    public E first()
    Description copied from interface: `SortedBag`
    Returns the first (lowest) member.
    Specified by:
      `first` in interface `SortedBag<E>`
    Returns:
      the first element in the sorted bag

  - ### getMap

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

  - ### last

    public E last()
    Description copied from interface: `SortedBag`
    Returns the last (highest) member.
    Specified by:
      `last` in interface `SortedBag<E>`
    Returns:
      the last element in the sorted bag