Class ArrayTable<R,C,V>
- java.lang.Object
-
- com.google.common.collect.ArrayTable<R,C,V>
-
- All Implemented Interfaces:
Table<R,C,V>
,java.io.Serializable
@GwtCompatible(emulated=true) public final class ArrayTable<R,C,V> extends java.lang.Object implements java.io.Serializable
Fixed-sizeTable
implementation backed by a two-dimensional array.Warning:
ArrayTable
is rarely theTable
implementation you want. First, it requires that the complete universe of rows and columns be specified at construction time. Second, it is always backed by an array large enough to hold a value for every possible combination of row and column keys. (This is rarely optimal unless the table is extremely dense.) Finally, every possible combination of row and column keys is always considered to have a value associated with it: It is not possible to "remove" a value, only to replace it withnull
, which will still appear when iterating over the table's contents in a foreach loop or a call to a null-hostile method likeImmutableTable.copyOf(com.google.common.collect.Table<? extends R, ? extends C, ? extends V>)
. For alternatives, please see the wiki.The allowed row and column keys must be supplied when the table is created. The table always contains a mapping for every row key / column pair. The value corresponding to a given row and column is null unless another value is provided.
The table's size is constant: the product of the number of supplied row keys and the number of supplied column keys. The
remove
andclear
methods are not supported by the table or its views. Theerase(java.lang.Object, java.lang.Object)
anderaseAll()
methods may be used instead.The ordering of the row and column keys provided when the table is constructed determines the iteration ordering across rows and columns in the table's views. None of the view iterators support
Iterator.remove()
. If the table is modified after an iterator is created, the iterator remains valid.This class requires less memory than the
HashBasedTable
andTreeBasedTable
implementations, except when the table is sparse.Null row keys or column keys are not permitted.
This class provides methods involving the underlying array structure, where the array indices correspond to the position of a row or column in the lists of allowed keys and values. See the
at(int, int)
,set(int, int, V)
,toArray(java.lang.Class<V>)
,rowKeyList()
, andcolumnKeyList()
methods for more details.Note that this implementation is not synchronized. If multiple threads access the same cell of an
ArrayTable
concurrently and one of the threads modifies its value, there is no guarantee that the new value will be fully visible to the other threads. To guarantee that modifications are visible, synchronize access to the table. Unlike otherTable
implementations, synchronization is unnecessary between a thread that writes to one cell and a thread that reads from another.See the Guava User Guide article on
Table
.- Since:
- 10.0
- Author:
- Jared Levy
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description V
at(int rowIndex, int columnIndex)
Returns the value corresponding to the specified row and column indices.java.util.Set<Table.Cell<R,C,@Nullable V>>
cellSet()
Returns an unmodifiable set of all row key / column key / value triplets.void
clear()
Deprecated.UseeraseAll()
java.util.Map<R,@Nullable V>
column(C columnKey)
Returns a view of all mappings that have the given column key.ImmutableList<C>
columnKeyList()
Returns, as an immutable list, the column keys provided when the table was constructed, including those that are mapped to null values only.ImmutableSet<C>
columnKeySet()
Returns an immutable set of the valid column keys, including those that are associated with null values only.java.util.Map<C,java.util.Map<R,@Nullable 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)
Returnstrue
if the provided keys are among the keys provided when the table was constructed.boolean
containsColumn(java.lang.Object columnKey)
Returnstrue
if the provided column key is among the column keys provided when the table was constructed.boolean
containsRow(java.lang.Object rowKey)
Returnstrue
if the provided row key is among the row keys provided when the table was constructed.boolean
containsValue(java.lang.Object value)
Returnstrue
if the table contains a mapping with the specified value.static <R,C,V>
ArrayTable<R,C,V>create(Table<R,C,? extends @Nullable V> table)
Creates anArrayTable
with the mappings in the provided table.static <R,C,V>
ArrayTable<R,C,V>create(java.lang.Iterable<? extends R> rowKeys, java.lang.Iterable<? extends C> columnKeys)
Creates anArrayTable
filled withnull
.boolean
equals(java.lang.Object obj)
Compares the specified object with this table for equality.V
erase(java.lang.Object rowKey, java.lang.Object columnKey)
Associates the valuenull
with the specified keys, assuming both keys are valid.void
eraseAll()
Associates the valuenull
with every pair of allowed row and column keys.V
get(java.lang.Object rowKey, java.lang.Object columnKey)
Returns the value corresponding to the given row and column keys, ornull
if no such mapping exists.int
hashCode()
Returns the hash code for this table.boolean
isEmpty()
Returnstrue
ifrowKeyList().size == 0
orcolumnKeyList().size() == 0
.V
put(R rowKey, C columnKey, V value)
Associates the specified value with the specified keys.void
putAll(Table<? extends R,? extends C,? extends @Nullable V> table)
Copies all mappings from the specified table to this table.V
remove(java.lang.Object rowKey, java.lang.Object columnKey)
Deprecated.java.util.Map<C,@Nullable V>
row(R rowKey)
Returns a view of all mappings that have the given row key.ImmutableList<R>
rowKeyList()
Returns, as an immutable list, the row keys provided when the table was constructed, including those that are mapped to null values only.ImmutableSet<R>
rowKeySet()
Returns an immutable set of the valid row keys, including those that are associated with null values only.java.util.Map<R,java.util.Map<C,@Nullable V>>
rowMap()
Returns a view that associates each row key with the corresponding map from column keys to values.V
set(int rowIndex, int columnIndex, V value)
Associatesvalue
with the specified row and column indices.int
size()
Returns the number of row key / column key / value mappings in the table.@Nullable V[][]
toArray(java.lang.Class<V> valueClass)
Returns a two-dimensional array with the table contents.java.lang.String
toString()
Returns the string representationrowMap().toString()
.java.util.Collection<@Nullable V>
values()
Returns an unmodifiable collection of all values, which may contain duplicates.
-
-
-
Method Detail
-
create
public static <R,C,V> ArrayTable<R,C,V> create(java.lang.Iterable<? extends R> rowKeys, java.lang.Iterable<? extends C> columnKeys)
Creates anArrayTable
filled withnull
.- Parameters:
rowKeys
- row keys that may be stored in the generated tablecolumnKeys
- column keys that may be stored in the generated table- Throws:
java.lang.NullPointerException
- if any of the provided keys is nulljava.lang.IllegalArgumentException
- ifrowKeys
orcolumnKeys
contains duplicates or if exactly one ofrowKeys
orcolumnKeys
is empty.
-
create
public static <R,C,V> ArrayTable<R,C,V> create(Table<R,C,? extends @Nullable V> table)
Creates anArrayTable
with the mappings in the provided table.If
table
includes a mapping with row keyr
and a separate mapping with column keyc
, the returned table contains a mapping with row keyr
and column keyc
. If that row key / column key pair in not intable
, the pair maps tonull
in the generated table.The returned table allows subsequent
put
calls with the row keys intable.rowKeySet()
and the column keys intable.columnKeySet()
. Callingput(R, C, V)
with other keys leads to anIllegalArgumentException
.The ordering of
table.rowKeySet()
andtable.columnKeySet()
determines the row and column iteration ordering of the returned table.- Throws:
java.lang.NullPointerException
- iftable
has a null key
-
rowKeyList
public ImmutableList<R> rowKeyList()
Returns, as an immutable list, the row keys provided when the table was constructed, including those that are mapped to null values only.
-
columnKeyList
public ImmutableList<C> columnKeyList()
Returns, as an immutable list, the column keys provided when the table was constructed, including those that are mapped to null values only.
-
at
@CheckForNull public V at(int rowIndex, int columnIndex)
Returns the value corresponding to the specified row and column indices. The same value is returned byget(rowKeyList().get(rowIndex), columnKeyList().get(columnIndex))
, but this method runs more quickly.- Parameters:
rowIndex
- position of the row key inrowKeyList()
columnIndex
- position of the row key incolumnKeyList()
- Returns:
- the value with the specified row and column
- Throws:
java.lang.IndexOutOfBoundsException
- if either index is negative,rowIndex
is greater than or equal to the number of allowed row keys, orcolumnIndex
is greater than or equal to the number of allowed column keys
-
set
@CanIgnoreReturnValue @CheckForNull public V set(int rowIndex, int columnIndex, @CheckForNull V value)
Associatesvalue
with the specified row and column indices. The logicput(rowKeyList().get(rowIndex), columnKeyList().get(columnIndex), value)
has the same behavior, but this method runs more quickly.- Parameters:
rowIndex
- position of the row key inrowKeyList()
columnIndex
- position of the row key incolumnKeyList()
value
- value to store in the table- Returns:
- the previous value with the specified row and column
- Throws:
java.lang.IndexOutOfBoundsException
- if either index is negative,rowIndex
is greater than or equal to the number of allowed row keys, orcolumnIndex
is greater than or equal to the number of allowed column keys
-
toArray
@GwtIncompatible public @Nullable V[][] toArray(java.lang.Class<V> valueClass)
Returns a two-dimensional array with the table contents. The row and column indices correspond to the positions of the row and column in the iterables provided during table construction. If the table lacks a mapping for a given row and column, the corresponding array element is null.Subsequent table changes will not modify the array, and vice versa.
- Parameters:
valueClass
- class of values stored in the returned array
-
clear
@Deprecated public void clear()
Deprecated.UseeraseAll()
Not supported. UseeraseAll()
instead.
-
eraseAll
public void eraseAll()
Associates the valuenull
with every pair of allowed row and column keys.
-
contains
public boolean contains(@CheckForNull java.lang.Object rowKey, @CheckForNull java.lang.Object columnKey)
Returnstrue
if the provided keys are among the keys provided when the table was constructed.
-
containsColumn
public boolean containsColumn(@CheckForNull java.lang.Object columnKey)
Returnstrue
if the provided column key is among the column keys provided when the table was constructed.- Specified by:
containsColumn
in interfaceTable<R,C,V>
- Parameters:
columnKey
- key of column to search for
-
containsRow
public boolean containsRow(@CheckForNull java.lang.Object rowKey)
Returnstrue
if the provided row key is among the row keys provided when the table was constructed.- Specified by:
containsRow
in interfaceTable<R,C,V>
- Parameters:
rowKey
- key of row to search for
-
containsValue
public boolean containsValue(@CheckForNull java.lang.Object value)
Description copied from interface:Table
Returnstrue
if the table contains a mapping with the specified value.- Specified by:
containsValue
in interfaceTable<R,C,V>
- Parameters:
value
- value to search for
-
get
@CheckForNull public V get(@CheckForNull java.lang.Object rowKey, @CheckForNull java.lang.Object columnKey)
Description copied from interface:Table
Returns the value corresponding to the given row and column keys, ornull
if no such mapping exists.
-
isEmpty
public boolean isEmpty()
Returnstrue
ifrowKeyList().size == 0
orcolumnKeyList().size() == 0
.
-
put
@CanIgnoreReturnValue @CheckForNull public V put(R rowKey, C columnKey, @CheckForNull V value)
Associates the specified value with the specified keys. If the table already contained a mapping for those keys, the old value is replaced with the specified value.- Specified by:
put
in interfaceTable<R,C,V>
- Parameters:
rowKey
- row key that the value should be associated withcolumnKey
- column key that the value should be associated withvalue
- 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.IllegalArgumentException
- ifrowKey
is not inrowKeySet()
orcolumnKey
is not incolumnKeySet()
.
-
putAll
public void putAll(Table<? extends R,? extends C,? extends @Nullable V> table)
Copies all mappings from the specified table to this table. The effect is equivalent to callingTable.put(R, C, V)
with each row key / column key / value mapping intable
.If
table
is anArrayTable
, its null values will be stored in this table, possibly replacing values that were previously non-null.- Specified by:
putAll
in interfaceTable<R,C,V>
- Parameters:
table
- the table to add to this table- Throws:
java.lang.NullPointerException
- iftable
has a null keyjava.lang.IllegalArgumentException
- if any of the provided table's row keys or column keys is not inrowKeySet()
orcolumnKeySet()
-
remove
@CanIgnoreReturnValue @Deprecated @CheckForNull public V remove(@CheckForNull java.lang.Object rowKey, @CheckForNull java.lang.Object columnKey)
Deprecated.Not supported. Useerase(java.lang.Object, java.lang.Object)
instead.
-
erase
@CanIgnoreReturnValue @CheckForNull public V erase(@CheckForNull java.lang.Object rowKey, @CheckForNull java.lang.Object columnKey)
Associates the valuenull
with the specified keys, assuming both keys are valid. If either key is null or isn't among the keys provided during construction, this method has no effect.This method is equivalent to
put(rowKey, columnKey, null)
when both provided keys are valid.- Parameters:
rowKey
- row key of mapping to be erasedcolumnKey
- column key of mapping to be erased- Returns:
- the value previously associated with the keys, or
null
if no mapping existed for the keys
-
size
public int size()
Description copied from interface:Table
Returns the number of row key / column key / value mappings in the table.
-
cellSet
public java.util.Set<Table.Cell<R,C,@Nullable V>> cellSet()
Returns an unmodifiable set of all row key / column key / value triplets. Changes to the table will update the returned set.The returned set's iterator traverses the mappings with the first row key, the mappings with the second row key, and so on.
The value in the returned cells may change if the table subsequently changes.
-
column
public java.util.Map<R,@Nullable V> column(C columnKey)
Returns a view of all mappings that have the given column key. If the column key isn't incolumnKeySet()
, an empty immutable map is returned.Otherwise, for each row key in
rowKeySet()
, the returned map associates the row key with the corresponding value in the table. Changes to the returned map will update the underlying table, and vice versa.
-
columnKeySet
public ImmutableSet<C> columnKeySet()
Returns an immutable set of the valid column keys, including those that are associated with null values only.- Specified by:
columnKeySet
in interfaceTable<R,C,V>
- Returns:
- immutable set of column keys
-
columnMap
public java.util.Map<C,java.util.Map<R,@Nullable V>> columnMap()
Description copied from interface:Table
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 supportput()
orputAll()
, orsetValue()
on its entries.In contrast, the maps returned by
columnMap().get()
have the same behavior as those returned byTable.column(C)
. Those maps may supportsetValue()
,put()
, andputAll()
.
-
row
public java.util.Map<C,@Nullable V> row(R rowKey)
Returns a view of all mappings that have the given row key. If the row key isn't inrowKeySet()
, an empty immutable map is returned.Otherwise, for each column key in
columnKeySet()
, the returned map associates the column key with the corresponding value in the table. Changes to the returned map will update the underlying table, and vice versa.
-
rowKeySet
public ImmutableSet<R> rowKeySet()
Returns an immutable set of the valid row keys, including those that are associated with null values only.
-
rowMap
public java.util.Map<R,java.util.Map<C,@Nullable V>> rowMap()
Description copied from interface:Table
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 supportput()
orputAll()
, orsetValue()
on its entries.In contrast, the maps returned by
rowMap().get()
have the same behavior as those returned byTable.row(R)
. Those maps may supportsetValue()
,put()
, andputAll()
.
-
values
public java.util.Collection<@Nullable V> values()
Returns an unmodifiable collection of all values, which may contain duplicates. Changes to the table will update the returned collection.The returned collection's iterator traverses the values of the first row key, the values of the second row key, and so on.
-
equals
public boolean equals(@CheckForNull 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 byTable.cellSet()
, are equal.
-
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 byTable.cellSet()
.
-
toString
public java.lang.String toString()
Returns the string representationrowMap().toString()
.- Overrides:
toString
in classjava.lang.Object
-
-