com.google.common.collect

## Class ImmutableMultiset.Builder<E>

- java.lang.Object
- - com.google.common.collect.ImmutableCollection.Builder<E>
  - - com.google.common.collect.ImmutableMultiset.Builder<E>

- Direct Known Subclasses:
    ImmutableSortedMultiset.Builder
  Enclosing class:
    ImmutableMultiset<E>

      public static class ImmutableMultiset.Builder<E>
      extends ImmutableCollection.Builder<E>

  A builder for creating immutable multiset instances, especially `public static final` multisets ("constant multisets"). Example:

       public static final ImmutableMultiset<Bean> BEANS =
             new ImmutableMultiset.Builder<Bean>()
                 .addCopies(Bean.COCOA, 4)
                 .addCopies(Bean.GARDEN, 6)
                 .addCopies(Bean.RED, 8)
                 .addCopies(Bean.BLACK_EYED, 10)
                 .build();

  Builder instances can be reused; it is safe to call `build()` multiple times to build multiple multisets in series.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImmutableMultiset.Builder()` Creates a new builder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableMultiset.Builder<E>` | `add(E... elements)` Adds each element of `elements` to the `ImmutableMultiset`.
    `ImmutableMultiset.Builder<E>` | `add(E element)` Adds `element` to the `ImmutableMultiset`.
    `ImmutableMultiset.Builder<E>` | `addAll(java.lang.Iterable<? extends E> elements)` Adds each element of `elements` to the `ImmutableMultiset`.
    `ImmutableMultiset.Builder<E>` | `addAll(java.util.Iterator<? extends E> elements)` Adds each element of `elements` to the `ImmutableMultiset`.
    `ImmutableMultiset.Builder<E>` | `addCopies(E element, int occurrences)` Adds a number of occurrences of an element to this `ImmutableMultiset`.
    `ImmutableMultiset<E>` | `build()` Returns a newly-created `ImmutableMultiset` based on the contents of the `Builder`.
    `ImmutableMultiset.Builder<E>` | `setCount(E element, int count)` Adds or removes the necessary occurrences of an element such that the element attains the desired count.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ImmutableMultiset.Builder

          public ImmutableMultiset.Builder()

      Creates a new builder. The returned builder is equivalent to the builder generated by `ImmutableMultiset.builder()`.

  - ### Method Detail

    - #### add

          public ImmutableMultiset.Builder<E> add(E element)

      Adds `element` to the `ImmutableMultiset`.
      Specified by:
        `add` in class `ImmutableCollection.Builder<E>`
      Parameters:
        `element` - the element to add
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `element` is null

    - #### addCopies

          public ImmutableMultiset.Builder<E> addCopies(E element,
                                               int occurrences)

      Adds a number of occurrences of an element to this `ImmutableMultiset`.
      Parameters:
        `element` - the element to add
        `occurrences` - the number of occurrences of the element to add. May be zero, in which case no change will be made.
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `element` is null
        `java.lang.IllegalArgumentException` - if `occurrences` is negative, or if this operation would result in more than `Integer.MAX_VALUE` occurrences of the element

    - #### setCount

          public ImmutableMultiset.Builder<E> setCount(E element,
                                              int count)

      Adds or removes the necessary occurrences of an element such that the element attains the desired count.
      Parameters:
        `element` - the element to add or remove occurrences of
        `count` - the desired count of the element in this multiset
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `element` is null
        `java.lang.IllegalArgumentException` - if `count` is negative

    - #### add

          public ImmutableMultiset.Builder<E> add(E... elements)

      Adds each element of `elements` to the `ImmutableMultiset`.
      Overrides:
        `add` in class `ImmutableCollection.Builder<E>`
      Parameters:
        `elements` - the elements to add
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `elements` is null or contains a null element

    - #### addAll

          public ImmutableMultiset.Builder<E> addAll(java.lang.Iterable<? extends E> elements)

      Adds each element of `elements` to the `ImmutableMultiset`.
      Overrides:
        `addAll` in class `ImmutableCollection.Builder<E>`
      Parameters:
        `elements` - the `Iterable` to add to the `ImmutableMultiset`
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `elements` is null or contains a null element

    - #### addAll

          public ImmutableMultiset.Builder<E> addAll(java.util.Iterator<? extends E> elements)

      Adds each element of `elements` to the `ImmutableMultiset`.
      Overrides:
        `addAll` in class `ImmutableCollection.Builder<E>`
      Parameters:
        `elements` - the elements to add to the `ImmutableMultiset`
      Returns:
        this `Builder` object
      Throws:
        `java.lang.NullPointerException` - if `elements` is null or contains a null element

    - #### build

          public ImmutableMultiset<E> build()

      Returns a newly-created `ImmutableMultiset` based on the contents of the `Builder`.
      Specified by:
        `build` in class `ImmutableCollection.Builder<E>`