ImmutableTable.Builder
Date: 2016-05-24

com.google.common.collect

## Class ImmutableTable.Builder<R,C,V>

- java.lang.Object
- - com.google.common.collect.ImmutableTable.Builder<R,C,V>

- Enclosing class:
    ImmutableTable<R,C,V>

      public static final class ImmutableTable.Builder<R,C,V>
      extends java.lang.Object

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

         static final ImmutableTable<Integer, Character, String> SPREADSHEET =
             new ImmutableTable.Builder<Integer, Character, String>()
                 .put(1, 'A', "foo")
                 .put(1, 'B', "bar")
                 .put(2, 'A', "baz")
                 .build();

  By default, the order in which cells are added to the builder determines the iteration ordering of all views in the returned table, with `putAll(com.google.common.collect.Table<? extends R, ? extends C, ? extends V>)` following the `Table.cellSet()` iteration order. However, if `orderRowsBy(java.util.Comparator<? super R>)` or `orderColumnsBy(java.util.Comparator<? super C>)` is called, the views are sorted by the supplied comparators. For empty or single-cell immutable tables, `ImmutableTable.of()` and `ImmutableTable.of(Object, Object, Object)` are even more convenient.

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

  Since:
    11.0

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ImmutableTable<R,C,V>` | `build()` Returns a newly-created immutable table.
    `ImmutableTable.Builder<R,C,V>` | `orderColumnsBy(java.util.Comparator<? super C> columnComparator)` Specifies the ordering of the generated table's columns.
    `ImmutableTable.Builder<R,C,V>` | `orderRowsBy(java.util.Comparator<? super R> rowComparator)` Specifies the ordering of the generated table's rows.
    `ImmutableTable.Builder<R,C,V>` | `put(R rowKey, C columnKey, V value)` Associates the (`rowKey`, `columnKey`) pair with `value` in the built table.
    `ImmutableTable.Builder<R,C,V>` | `put(Table.Cell<? extends R,? extends C,? extends V> cell)` Adds the given `cell` to the table, making it immutable if necessary.
    `ImmutableTable.Builder<R,C,V>` | `putAll(Table<? extends R,? extends C,? extends V> table)` Associates all of the given table's keys and values in the built table.

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

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

- - ### Constructor Detail

    - #### ImmutableTable.Builder

          public ImmutableTable.Builder()

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

  - ### Method Detail

    - #### orderRowsBy

          public ImmutableTable.Builder<R,C,V> orderRowsBy(java.util.Comparator<? super R> rowComparator)

      Specifies the ordering of the generated table's rows.

    - #### orderColumnsBy

          public ImmutableTable.Builder<R,C,V> orderColumnsBy(java.util.Comparator<? super C> columnComparator)

      Specifies the ordering of the generated table's columns.

    - #### put

          public ImmutableTable.Builder<R,C,V> put(R rowKey,
                                          C columnKey,
                                          V value)

      Associates the (`rowKey`, `columnKey`) pair with `value` in the built table. Duplicate key pairs are not allowed and will cause `build()` to fail.

    - #### put

          public ImmutableTable.Builder<R,C,V> put(Table.Cell<? extends R,? extends C,? extends V> cell)

      Adds the given `cell` to the table, making it immutable if necessary. Duplicate key pairs are not allowed and will cause `build()` to fail.

    - #### putAll

          public ImmutableTable.Builder<R,C,V> putAll(Table<? extends R,? extends C,? extends V> table)

      Associates all of the given table's keys and values in the built table. Duplicate row key column key pairs are not allowed, and will cause `build()` to fail.
      Throws:
        `java.lang.NullPointerException` - if any key or value in `table` is null

    - #### build

          public ImmutableTable<R,C,V> build()

      Returns a newly-created immutable table.
      Throws:
        `java.lang.IllegalArgumentException` - if duplicate key pairs were added