ImmutableBiMap.Builder
Date: 2016-05-24

com.google.common.collect

## Class ImmutableBiMap.Builder<K,V>

- java.lang.Object
- - com.google.common.collect.ImmutableMap.Builder<K,V>
  - - com.google.common.collect.ImmutableBiMap.Builder<K,V>

- Enclosing class:
    ImmutableBiMap<K,V>

      public static final class ImmutableBiMap.Builder<K,V>
      extends ImmutableMap.Builder<K,V>

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

         static final ImmutableBiMap<String, Integer> WORD_TO_INT =
             new ImmutableBiMap.Builder<String, Integer>()
                 .put("one", 1)
                 .put("two", 2)
                 .put("three", 3)
                 .build();

  For small immutable bimaps, the `ImmutableBiMap.of()` methods are even more convenient.

  Builder instances can be reused - it is safe to call `build()` multiple times to build multiple bimaps in series. Each bimap is a superset of the bimaps created before it.

  Since:
    2.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableBiMap<K,V>` | `build()` Returns a newly-created immutable bimap.
    `ImmutableBiMap.Builder<K,V>` | `orderEntriesByValue(java.util.Comparator<? super V> valueComparator)` Configures this `Builder` to order entries by value according to the specified comparator.
    `ImmutableBiMap.Builder<K,V>` | `put(K key, V value)` Associates `key` with `value` in the built bimap.
    `ImmutableBiMap.Builder<K,V>` | `put(java.util.Map.Entry<? extends K,? extends V> entry)` Adds the given `entry` to the bimap.
    `ImmutableBiMap.Builder<K,V>` | `putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)` Adds all of the given entries to the built bimap.
    `ImmutableBiMap.Builder<K,V>` | `putAll(java.util.Map<? extends K,? extends V> map)` Associates all of the given map's keys and values in the built bimap.

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

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

- - ### Constructor Detail

    - #### ImmutableBiMap.Builder

          public ImmutableBiMap.Builder()

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

  - ### Method Detail

    - #### put

          public ImmutableBiMap.Builder<K,V> put(K key,
                                        V value)

      Associates `key` with `value` in the built bimap. Duplicate keys or values are not allowed, and will cause `build()` to fail.
      Overrides:
        `put` in class `ImmutableMap.Builder<K,V>`

    - #### put

          public ImmutableBiMap.Builder<K,V> put(java.util.Map.Entry<? extends K,? extends V> entry)

      Adds the given `entry` to the bimap. Duplicate keys or values are not allowed, and will cause `build()` to fail.
      Overrides:
        `put` in class `ImmutableMap.Builder<K,V>`
      Since:
        19.0

    - #### putAll

          public ImmutableBiMap.Builder<K,V> putAll(java.util.Map<? extends K,? extends V> map)

      Associates all of the given map's keys and values in the built bimap. Duplicate keys or values are not allowed, and will cause `build()` to fail.
      Overrides:
        `putAll` in class `ImmutableMap.Builder<K,V>`
      Throws:
        `java.lang.NullPointerException` - if any key or value in `map` is null

    - #### putAll

          @Beta
          public ImmutableBiMap.Builder<K,V> putAll(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)

      Adds all of the given entries to the built bimap. Duplicate keys or values are not allowed, and will cause `build()` to fail.
      Overrides:
        `putAll` in class `ImmutableMap.Builder<K,V>`
      Throws:
        `java.lang.NullPointerException` - if any key, value, or entry is null
      Since:
        19.0

    - #### orderEntriesByValue

          @Beta
          public ImmutableBiMap.Builder<K,V> orderEntriesByValue(java.util.Comparator<? super V> valueComparator)

      Configures this `Builder` to order entries by value according to the specified comparator.

      The sort order is stable, that is, if two entries have values that compare as equivalent, the entry that was inserted first will be first in the built map's iteration order.

      Overrides:
        `orderEntriesByValue` in class `ImmutableMap.Builder<K,V>`
      Throws:
        `java.lang.IllegalStateException` - if this method was already called
      Since:
        19.0

    - #### build

          public ImmutableBiMap<K,V> build()

      Returns a newly-created immutable bimap.
      Overrides:
        `build` in class `ImmutableMap.Builder<K,V>`
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate keys or values were added