Package org.apache.commons.collections4.multiset

# Class TreeMultiSet<E>

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

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

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

public class TreeMultiSet<E> extends AbstractMapMultiSet<E> implements SortedMultiSet<E>, Serializable
Implements `SortedMultiSet`, using a `TreeMap` to provide the data storage. This is the standard implementation of a sorted multiset.

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

A `MultiSet` 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.

Note that TreeMultiSet is not synchronized and is not thread-safe. If you wish to use this multiset from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this multiset using `MultiSetUtils.synchronizedSortedMultiSet(SortedMultiSet)`. Unsynchronized concurrent modification can corrupt the structure of the backing `TreeMap`, and a malformed tree may cause subsequent operations, including reads, to enter an infinite loop.

Since:
  4.6.0
See Also:
  - Serialized Form

- ## Nested Class Summary

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

  `AbstractMapMultiSet.EntrySetIterator<E>, AbstractMapMultiSet.MultiSetEntry<E>, AbstractMapMultiSet.MutableInteger, AbstractMapMultiSet.UniqueSetIterator<E>`

  ## 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
  Constructor
  Description
  `TreeMultiSet()`
  Constructs an empty `TreeMultiSet`.
  `TreeMultiSet(Iterable<? extends E> iterable)`
  Constructs a multiset containing all the members of the given Iterable.
  `TreeMultiSet(Collection<? extends E> coll)`
  Constructs a `TreeMultiSet` containing all the members of the specified collection.
  `TreeMultiSet(Comparator<? super E> comparator)`
  Constructs an empty multiset that maintains order on its unique representative members according to the given `Comparator`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `add(E object, int occurrences)`
  Always throws `UnsupportedOperationException`.
  `Comparator<? super E>`
  `comparator()`
  Returns the comparator associated with this sorted multiset, or null if it uses its elements' natural ordering.
  `E`
  `first()`
  Returns the first (lowest) member.
  `protected SortedMap<E,AbstractMapMultiSet.MutableInteger>`
  `getMap()`
  Gets the map that backs this multiset.
  `E`
  `last()`
  Returns the last (highest) member.

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

  `clear, contains, createEntrySetIterator, createUniqueSetIterator, doReadObject, doWriteObject, equals, getCount, hashCode, isEmpty, iterator, remove, setMap, size, toArray, toArray, uniqueElements`

  ### 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, clear, contains, isEmpty, parallelStream, removeIf, spliterator, stream, toArray, toArray`

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

  `forEach`

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

  `add, containsAll, entrySet, equals, getCount, hashCode, iterator, remove, remove, removeAll, retainAll, setCount, size, uniqueSet`

- ## Constructor Details

  - ### TreeMultiSet

    public TreeMultiSet()
    Constructs an empty `TreeMultiSet`.

  - ### TreeMultiSet

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

  - ### TreeMultiSet

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

  - ### TreeMultiSet

    public TreeMultiSet(Iterable<? extends E> iterable)
    Constructs a multiset containing all the members of the given Iterable.
    Parameters:
      `iterable` - An iterable to copy into this multiset.
    Since:
      4.6.0

- ## Method Details

  - ### add

    public int add(E object, int occurrences)
    Always throws `UnsupportedOperationException`.
    Specified by:
      `add` in interface `MultiSet<E>`
    Overrides:
      `add` in class `AbstractMapMultiSet<E>`
    Parameters:
      `object` - Ignored.
      `occurrences` - Ignored.
    Returns:
      The number of occurrences of the object in the multiset before this operation; possibly zero.
    Throws:
      `IllegalArgumentException` - if the object to be added does not implement `Comparable` and the `TreeMultiSet` is using natural ordering
      `NullPointerException` - if the specified key is null and this multiset uses natural ordering, or its comparator does not permit null keys

  - ### comparator

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

  - ### first

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

  - ### getMap

    protected SortedMap<E,AbstractMapMultiSet.MutableInteger> getMap()
    Description copied from class: `AbstractMapMultiSet`
    Gets the map that backs this multiset. Not intended for interactive use outside of subclasses.
    Overrides:
      `getMap` in class `AbstractMapMultiSet<E>`
    Returns:
      The map being used by the MultiSet.

  - ### last

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