ImmutableTable
Date: 2016-05-24

com.google.common.collect

## Class ImmutableTable<R,C,V>

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

- All Implemented Interfaces:
    Table<R,C,V>

      @GwtCompatible
      public abstract class ImmutableTable<R,C,V>
      extends java.lang.Object

  A `Table` whose contents will never change, with many other important properties detailed at `ImmutableCollection`.

  See the Guava User Guide article on immutable collections.

  Since:
    11.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ImmutableTable.Builder<R,C,V>` A builder for creating immutable table instances, especially `public static final` tables ("constant tables").

    - ### Nested classes/interfaces inherited from interface com.google.common.collect.Table

      `Table.Cell<R,C,V>`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <R,C,V> ImmutableTable.Builder<R,C,V>` | `builder()` Returns a new builder.
    `ImmutableSet<Table.Cell<R,C,V>>` | `cellSet()` Returns a set of all row key / column key / value triplets.
    `void` | `clear()` Deprecated. Unsupported operation.
    `ImmutableMap<R,V>` | `column(C columnKey)` Returns a view of all mappings that have the given column key.
    `ImmutableSet<C>` | `columnKeySet()` Returns a set of column keys that have one or more values in the table.
    `abstract ImmutableMap<C,java.util.Map<R,V>>` | `columnMap()` Returns a view that associates each column key with the corresponding map from row keys to values.
    `boolean` | `contains(java.lang.Object rowKey, java.lang.Object columnKey)` Returns `true` if the table contains a mapping with the specified row and column keys.
    `boolean` | `containsColumn(java.lang.Object columnKey)` Returns `true` if the table contains a mapping with the specified column.
    `boolean` | `containsRow(java.lang.Object rowKey)` Returns `true` if the table contains a mapping with the specified row key.
    `boolean` | `containsValue(java.lang.Object value)` Returns `true` if the table contains a mapping with the specified value.
    `static <R,C,V> ImmutableTable<R,C,V>` | `copyOf(Table<? extends R,? extends C,? extends V> table)` Returns an immutable copy of the provided table.
    `boolean` | `equals(java.lang.Object obj)` Compares the specified object with this table for equality.
    `V` | `get(java.lang.Object rowKey, java.lang.Object columnKey)` Returns the value corresponding to the given row and column keys, or `null` if no such mapping exists.
    `int` | `hashCode()` Returns the hash code for this table.
    `boolean` | `isEmpty()` Returns `true` if the table contains no mappings.
    `static <R,C,V> ImmutableTable<R,C,V>` | `of()` Returns an empty immutable table.
    `static <R,C,V> ImmutableTable<R,C,V>` | `of(R rowKey, C columnKey, V value)` Returns an immutable table containing a single cell.
    `V` | `put(R rowKey, C columnKey, V value)` Deprecated. Unsupported operation.
    `void` | `putAll(Table<? extends R,? extends C,? extends V> table)` Deprecated. Unsupported operation.
    `V` | `remove(java.lang.Object rowKey, java.lang.Object columnKey)` Deprecated. Unsupported operation.
    `ImmutableMap<C,V>` | `row(R rowKey)` Returns a view of all mappings that have the given row key.
    `ImmutableSet<R>` | `rowKeySet()` Returns a set of row keys that have one or more values in the table.
    `abstract ImmutableMap<R,java.util.Map<C,V>>` | `rowMap()` Returns a view that associates each row key with the corresponding map from column keys to values.
    `java.lang.String` | `toString()` Returns the string representation `rowMap().toString()`.
    `ImmutableCollection<V>` | `values()` Returns a collection of all values, which may contain duplicates.

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

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

    - ### Methods inherited from interface com.google.common.collect.Table

      `size`

- - ### Method Detail

    - #### of

          public static <R,C,V> ImmutableTable<R,C,V> of()

      Returns an empty immutable table.

    - #### of

          public static <R,C,V> ImmutableTable<R,C,V> of(R rowKey,
                                         C columnKey,
                                         V value)

      Returns an immutable table containing a single cell.

    - #### copyOf

          public static <R,C,V> ImmutableTable<R,C,V> copyOf(Table<? extends R,? extends C,? extends V> table)

      Returns an immutable copy of the provided table.

      The `Table.cellSet()` iteration order of the provided table determines the iteration ordering of all views in the returned table. Note that some views of the original table and the copied table may have different iteration orders. For more control over the ordering, create a `ImmutableTable.Builder` and call `ImmutableTable.Builder.orderRowsBy(java.util.Comparator<? super R>)`, `ImmutableTable.Builder.orderColumnsBy(java.util.Comparator<? super C>)`, and `ImmutableTable.Builder.putAll(com.google.common.collect.Table<? extends R, ? extends C, ? extends V>)`

      Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

    - #### builder

          public static <R,C,V> ImmutableTable.Builder<R,C,V> builder()

      Returns a new builder. The generated builder is equivalent to the builder created by the `ImmutableTable.Builder.ImmutableTable.Builder()` constructor.

    - #### cellSet

          public ImmutableSet<Table.Cell<R,C,V>> cellSet()

      Description copied from interface: `Table`
      Returns a set of all row key / column key / value triplets. Changes to the returned set will update the underlying table, and vice versa. The cell set does not support the `add` or `addAll` methods.
      Specified by:
        `cellSet` in interface `Table<R,C,V>`
      Returns:
        set of table cells consisting of row key / column key / value triplets

    - #### values

          public ImmutableCollection<V> values()

      Description copied from interface: `Table`
      Returns a collection of all values, which may contain duplicates. Changes to the returned collection will update the underlying table, and vice versa.
      Specified by:
        `values` in interface `Table<R,C,V>`
      Returns:
        collection of values

    - #### column

          public ImmutableMap<R,V> column(C columnKey)

      Returns a view of all mappings that have the given column key. For each row key / column key / value mapping in the table with that column key, the returned map associates the row key with the value. If no mappings in the table have the provided column key, an empty map is returned.

      Changes to the returned map will update the underlying table, and vice versa.

      Parameters:
        `columnKey` - key of column to search for in the table
      Returns:
        the corresponding map from row keys to values
      Throws:
        `java.lang.NullPointerException` - if `columnKey` is `null`

    - #### columnKeySet

          public ImmutableSet<C> columnKeySet()

      Description copied from interface: `Table`
      Returns a set of column keys that have one or more values in the table. Changes to the set will update the underlying table, and vice versa.
      Specified by:
        `columnKeySet` in interface `Table<R,C,V>`
      Returns:
        set of column keys

    - #### columnMap

          public abstract ImmutableMap<C,java.util.Map<R,V>> columnMap()

      Returns a view that associates each column key with the corresponding map from row keys to values. Changes to the returned map will update this table. The returned map does not support `put()` or `putAll()`, or `setValue()` on its entries.

      In contrast, the maps returned by `columnMap().get()` have the same behavior as those returned by `Table.column(C)`. Those maps may support `setValue()`, `put()`, and `putAll()`.

      The value `Map<R, V>` instances in the returned map are `ImmutableMap` instances as well.

      Returns:
        a map view from each column key to a secondary map from row keys to values

    - #### row

          public ImmutableMap<C,V> row(R rowKey)

      Returns a view of all mappings that have the given row key. For each row key / column key / value mapping in the table with that row key, the returned map associates the column key with the value. If no mappings in the table have the provided row key, an empty map is returned.

      Changes to the returned map will update the underlying table, and vice versa.

      Parameters:
        `rowKey` - key of row to search for in the table
      Returns:
        the corresponding map from column keys to values
      Throws:
        `java.lang.NullPointerException` - if `rowKey` is `null`

    - #### rowKeySet

          public ImmutableSet<R> rowKeySet()

      Description copied from interface: `Table`
      Returns a set of row keys that have one or more values in the table. Changes to the set will update the underlying table, and vice versa.
      Specified by:
        `rowKeySet` in interface `Table<R,C,V>`
      Returns:
        set of row keys

    - #### rowMap

          public abstract ImmutableMap<R,java.util.Map<C,V>> rowMap()

      Returns a view that associates each row key with the corresponding map from column keys to values. Changes to the returned map will update this table. The returned map does not support `put()` or `putAll()`, or `setValue()` on its entries.

      In contrast, the maps returned by `rowMap().get()` have the same behavior as those returned by `Table.row(R)`. Those maps may support `setValue()`, `put()`, and `putAll()`.

      The value `Map<C, V>` instances in the returned map are `ImmutableMap` instances as well.

      Returns:
        a map view from each row key to a secondary map from column keys to values

    - #### contains

          public boolean contains(@Nullable
                         java.lang.Object rowKey,
                         @Nullable
                         java.lang.Object columnKey)

      Description copied from interface: `Table`
      Returns `true` if the table contains a mapping with the specified row and column keys.
      Specified by:
        `contains` in interface `Table<R,C,V>`
      Parameters:
        `rowKey` - key of row to search for
        `columnKey` - key of column to search for

    - #### containsValue

          public boolean containsValue(@Nullable
                              java.lang.Object value)

      Description copied from interface: `Table`
      Returns `true` if the table contains a mapping with the specified value.
      Specified by:
        `containsValue` in interface `Table<R,C,V>`
      Parameters:
        `value` - value to search for

    - #### clear

          @Deprecated
          public final void clear()

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the table unmodified.
      Specified by:
        `clear` in interface `Table<R,C,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### put

          @Deprecated
          public final V put(R rowKey,
                         C columnKey,
                         V value)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the table unmodified.
      Specified by:
        `put` in interface `Table<R,C,V>`
      Parameters:
        `rowKey` - row key that the value should be associated with
        `columnKey` - column key that the value should be associated with
        `value` - value to be associated with the specified keys
      Returns:
        the value previously associated with the keys, or `null` if no mapping existed for the keys
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### putAll

          @Deprecated
          public final void putAll(Table<? extends R,? extends C,? extends V> table)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the table unmodified.
      Specified by:
        `putAll` in interface `Table<R,C,V>`
      Parameters:
        `table` - the table to add to this table
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### remove

          @Deprecated
          public final V remove(java.lang.Object rowKey,
                            java.lang.Object columnKey)

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the table unmodified.
      Specified by:
        `remove` in interface `Table<R,C,V>`
      Parameters:
        `rowKey` - row key of mapping to be removed
        `columnKey` - column key of mapping to be removed
      Returns:
        the value previously associated with the keys, or `null` if no such value existed
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### containsRow

          public boolean containsRow(@Nullable
                            java.lang.Object rowKey)

      Description copied from interface: `Table`
      Returns `true` if the table contains a mapping with the specified row key.
      Specified by:
        `containsRow` in interface `Table<R,C,V>`
      Parameters:
        `rowKey` - key of row to search for

    - #### containsColumn

          public boolean containsColumn(@Nullable
                               java.lang.Object columnKey)

      Description copied from interface: `Table`
      Returns `true` if the table contains a mapping with the specified column.
      Specified by:
        `containsColumn` in interface `Table<R,C,V>`
      Parameters:
        `columnKey` - key of column to search for

    - #### get

          public V get(@Nullable
              java.lang.Object rowKey,
              @Nullable
              java.lang.Object columnKey)

      Description copied from interface: `Table`
      Returns the value corresponding to the given row and column keys, or `null` if no such mapping exists.
      Specified by:
        `get` in interface `Table<R,C,V>`
      Parameters:
        `rowKey` - key of row to search for
        `columnKey` - key of column to search for

    - #### isEmpty

          public boolean isEmpty()

      Description copied from interface: `Table`
      Returns `true` if the table contains no mappings.
      Specified by:
        `isEmpty` in interface `Table<R,C,V>`

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object obj)

      Description copied from interface: `Table`
      Compares the specified object with this table for equality. Two tables are equal when their cell views, as returned by `Table.cellSet()`, are equal.
      Specified by:
        `equals` in interface `Table<R,C,V>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Description copied from interface: `Table`
      Returns the hash code for this table. The hash code of a table is defined as the hash code of its cell view, as returned by `Table.cellSet()`.
      Specified by:
        `hashCode` in interface `Table<R,C,V>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Returns the string representation `rowMap().toString()`.
      Overrides:
        `toString` in class `java.lang.Object`