com.google.common.collect.ImmutableTable Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* Copyright (C) 2009 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.collect;
import static com.google.common.base.Preconditions.checkNotNull;
import com.google.common.annotations.GwtCompatible;
import com.google.common.base.MoreObjects;
import com.google.common.collect.Tables.AbstractCell;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import com.google.errorprone.annotations.DoNotMock;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Spliterator;
import java.util.function.BinaryOperator;
import java.util.function.Function;
import java.util.function.Supplier;
import java.util.stream.Collector;
import org.checkerframework.checker.nullness.qual.Nullable;
/**
* A {@link Table} whose contents will never change, with many other important properties detailed
* at {@link ImmutableCollection}.
*
* See the Guava User Guide article on immutable collections.
*
* @author Gregory Kick
* @since 11.0
*/
@GwtCompatible
public abstract class ImmutableTable extends AbstractTable
implements Serializable {
/**
* Returns a {@code Collector} that accumulates elements into an {@code ImmutableTable}. Each
* input element is mapped to one cell in the returned table, with the rows, columns, and values
* generated by applying the specified functions.
*
* The returned {@code Collector} will throw a {@code NullPointerException} at collection time
* if the row, column, or value functions return null on any input.
*
* @since 21.0
*/
public static Collector> toImmutableTable(
Function rowFunction,
Function columnFunction,
Function valueFunction) {
checkNotNull(rowFunction, "rowFunction");
checkNotNull(columnFunction, "columnFunction");
checkNotNull(valueFunction, "valueFunction");
return Collector.of(
(Supplier>) Builder::new,
(builder, t) ->
builder.put(rowFunction.apply(t), columnFunction.apply(t), valueFunction.apply(t)),
Builder::combine,
Builder::build);
}
/**
* Returns a {@code Collector} that accumulates elements into an {@code ImmutableTable}. Each
* input element is mapped to one cell in the returned table, with the rows, columns, and values
* generated by applying the specified functions. If multiple inputs are mapped to the same row
* and column pair, they will be combined with the specified merging function in encounter order.
*
* The returned {@code Collector} will throw a {@code NullPointerException} at collection time
* if the row, column, value, or merging functions return null on any input.
*
* @since 21.0
*/
public static Collector> toImmutableTable(
Function rowFunction,
Function columnFunction,
Function valueFunction,
BinaryOperator mergeFunction) {
checkNotNull(rowFunction, "rowFunction");
checkNotNull(columnFunction, "columnFunction");
checkNotNull(valueFunction, "valueFunction");
checkNotNull(mergeFunction, "mergeFunction");
/*
* No mutable Table exactly matches the insertion order behavior of ImmutableTable.Builder, but
* the Builder can't efficiently support merging of duplicate values. Getting around this
* requires some work.
*/
return Collector.of(
() -> new CollectorState()
/* GWT isn't currently playing nicely with constructor references? */ ,
(state, input) ->
state.put(
rowFunction.apply(input),
columnFunction.apply(input),
valueFunction.apply(input),
mergeFunction),
(s1, s2) -> s1.combine(s2, mergeFunction),
state -> state.toTable());
}
private static final class CollectorState {
final List> insertionOrder = new ArrayList<>();
final Table> table = HashBasedTable.create();
void put(R row, C column, V value, BinaryOperator merger) {
MutableCell oldCell = table.get(row, column);
if (oldCell == null) {
MutableCell cell = new MutableCell<>(row, column, value);
insertionOrder.add(cell);
table.put(row, column, cell);
} else {
oldCell.merge(value, merger);
}
}
CollectorState combine(CollectorState other, BinaryOperator merger) {
for (MutableCell cell : other.insertionOrder) {
put(cell.getRowKey(), cell.getColumnKey(), cell.getValue(), merger);
}
return this;
}
ImmutableTable toTable() {
return copyOf(insertionOrder);
}
}
private static final class MutableCell extends AbstractCell {
private final R row;
private final C column;
private V value;
MutableCell(R row, C column, V value) {
this.row = checkNotNull(row, "row");
this.column = checkNotNull(column, "column");
this.value = checkNotNull(value, "value");
}
@Override
public R getRowKey() {
return row;
}
@Override
public C getColumnKey() {
return column;
}
@Override
public V getValue() {
return value;
}
void merge(V value, BinaryOperator mergeFunction) {
checkNotNull(value, "value");
this.value = checkNotNull(mergeFunction.apply(this.value, value), "mergeFunction.apply");
}
}
/** Returns an empty immutable table. */
@SuppressWarnings("unchecked")
public static ImmutableTable of() {
return (ImmutableTable) SparseImmutableTable.EMPTY;
}
/** Returns an immutable table containing a single cell. */
public static ImmutableTable of(R rowKey, C columnKey, V value) {
return new SingletonImmutableTable<>(rowKey, columnKey, value);
}
/**
* Returns an immutable copy of the provided table.
*
* The {@link 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
* {@link Builder} and call {@link Builder#orderRowsBy}, {@link Builder#orderColumnsBy}, and
* {@link Builder#putAll}
*
*
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.
*/
public static ImmutableTable copyOf(
Table table) {
if (table instanceof ImmutableTable) {
@SuppressWarnings("unchecked")
ImmutableTable parameterizedTable = (ImmutableTable) table;
return parameterizedTable;
} else {
return copyOf(table.cellSet());
}
}
private static ImmutableTable copyOf(
Iterable> cells) {
ImmutableTable.Builder builder = ImmutableTable.builder();
for (Cell cell : cells) {
builder.put(cell);
}
return builder.build();
}
/**
* Returns a new builder. The generated builder is equivalent to the builder created by the {@link
* Builder#Builder() ImmutableTable.Builder()} constructor.
*/
public static Builder builder() {
return new Builder<>();
}
/**
* Verifies that {@code rowKey}, {@code columnKey} and {@code value} are non-null, and returns a
* new entry with those values.
*/
static Cell cellOf(R rowKey, C columnKey, V value) {
return Tables.immutableCell(
checkNotNull(rowKey, "rowKey"),
checkNotNull(columnKey, "columnKey"),
checkNotNull(value, "value"));
}
/**
* A builder for creating immutable table instances, especially {@code public static final} tables
* ("constant tables"). Example:
*
* {@code
* static final ImmutableTable SPREADSHEET =
* new ImmutableTable.Builder()
* .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 {@link #putAll} following the {@link
* Table#cellSet()} iteration order. However, if {@link #orderRowsBy} or {@link #orderColumnsBy}
* is called, the views are sorted by the supplied comparators.
*
*
For empty or single-cell immutable tables, {@link #of()} and {@link #of(Object, Object,
* Object)} are even more convenient.
*
*
Builder instances can be reused - it is safe to call {@link #build} multiple times to build
* multiple tables in series. Each table is a superset of the tables created before it.
*
* @since 11.0
*/
@DoNotMock
public static final class Builder {
private final List> cells = Lists.newArrayList();
private @Nullable Comparator rowComparator;
private @Nullable Comparator columnComparator;
/**
* Creates a new builder. The returned builder is equivalent to the builder generated by {@link
* ImmutableTable#builder}.
*/
public Builder() {}
/** Specifies the ordering of the generated table's rows. */
@CanIgnoreReturnValue
public Builder orderRowsBy(Comparator rowComparator) {
this.rowComparator = checkNotNull(rowComparator, "rowComparator");
return this;
}
/** Specifies the ordering of the generated table's columns. */
@CanIgnoreReturnValue
public Builder orderColumnsBy(Comparator columnComparator) {
this.columnComparator = checkNotNull(columnComparator, "columnComparator");
return this;
}
/**
* Associates the ({@code rowKey}, {@code columnKey}) pair with {@code value} in the built
* table. Duplicate key pairs are not allowed and will cause {@link #build} to fail.
*/
@CanIgnoreReturnValue
public Builder put(R rowKey, C columnKey, V value) {
cells.add(cellOf(rowKey, columnKey, value));
return this;
}
/**
* Adds the given {@code cell} to the table, making it immutable if necessary. Duplicate key
* pairs are not allowed and will cause {@link #build} to fail.
*/
@CanIgnoreReturnValue
public Builder put(Cell cell) {
if (cell instanceof Tables.ImmutableCell) {
checkNotNull(cell.getRowKey(), "row");
checkNotNull(cell.getColumnKey(), "column");
checkNotNull(cell.getValue(), "value");
@SuppressWarnings("unchecked") // all supported methods are covariant
Cell immutableCell = (Cell) cell;
cells.add(immutableCell);
} else {
put(cell.getRowKey(), cell.getColumnKey(), cell.getValue());
}
return this;
}
/**
* 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 {@link #build} to fail.
*
* @throws NullPointerException if any key or value in {@code table} is null
*/
@CanIgnoreReturnValue
public Builder putAll(Table table) {
for (Cell cell : table.cellSet()) {
put(cell);
}
return this;
}
Builder combine(Builder other) {
this.cells.addAll(other.cells);
return this;
}
/**
* Returns a newly-created immutable table.
*
* @throws IllegalArgumentException if duplicate key pairs were added
*/
public ImmutableTable build() {
int size = cells.size();
switch (size) {
case 0:
return of();
case 1:
return new SingletonImmutableTable<>(Iterables.getOnlyElement(cells));
default:
return RegularImmutableTable.forCells(cells, rowComparator, columnComparator);
}
}
}
ImmutableTable() {}
@Override
public ImmutableSet> cellSet() {
return (ImmutableSet>) super.cellSet();
}
@Override
abstract ImmutableSet> createCellSet();
@Override
final UnmodifiableIterator> cellIterator() {
throw new AssertionError("should never be called");
}
@Override
final Spliterator> cellSpliterator() {
throw new AssertionError("should never be called");
}
@Override
public ImmutableCollection values() {
return (ImmutableCollection) super.values();
}
@Override
abstract ImmutableCollection createValues();
@Override
final Iterator valuesIterator() {
throw new AssertionError("should never be called");
}
/**
* {@inheritDoc}
*
* @throws NullPointerException if {@code columnKey} is {@code null}
*/
@Override
public ImmutableMap column(C columnKey) {
checkNotNull(columnKey, "columnKey");
return MoreObjects.firstNonNull(
(ImmutableMap) columnMap().get(columnKey), ImmutableMap.of());
}
@Override
public ImmutableSet columnKeySet() {
return columnMap().keySet();
}
/**
* {@inheritDoc}
*
* The value {@code Map} instances in the returned map are {@link ImmutableMap} instances
* as well.
*/
@Override
public abstract ImmutableMap> columnMap();
/**
* {@inheritDoc}
*
* @throws NullPointerException if {@code rowKey} is {@code null}
*/
@Override
public ImmutableMap row(R rowKey) {
checkNotNull(rowKey, "rowKey");
return MoreObjects.firstNonNull(
(ImmutableMap) rowMap().get(rowKey), ImmutableMap.of());
}
@Override
public ImmutableSet rowKeySet() {
return rowMap().keySet();
}
/**
* {@inheritDoc}
*
* The value {@code Map} instances in the returned map are {@link ImmutableMap} instances
* as well.
*/
@Override
public abstract ImmutableMap> rowMap();
@Override
public boolean contains(@Nullable Object rowKey, @Nullable Object columnKey) {
return get(rowKey, columnKey) != null;
}
@Override
public boolean containsValue(@Nullable Object value) {
return values().contains(value);
}
/**
* Guaranteed to throw an exception and leave the table unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@Deprecated
@Override
public final void clear() {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the table unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final V put(R rowKey, C columnKey, V value) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the table unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@Deprecated
@Override
public final void putAll(Table table) {
throw new UnsupportedOperationException();
}
/**
* Guaranteed to throw an exception and leave the table unmodified.
*
* @throws UnsupportedOperationException always
* @deprecated Unsupported operation.
*/
@CanIgnoreReturnValue
@Deprecated
@Override
public final V remove(Object rowKey, Object columnKey) {
throw new UnsupportedOperationException();
}
/** Creates the common serialized form for this table. */
abstract SerializedForm createSerializedForm();
/**
* Serialized type for all ImmutableTable instances. It captures the logical contents and
* preserves iteration order of all views.
*/
static final class SerializedForm implements Serializable {
private final Object[] rowKeys;
private final Object[] columnKeys;
private final Object[] cellValues;
private final int[] cellRowIndices;
private final int[] cellColumnIndices;
private SerializedForm(
Object[] rowKeys,
Object[] columnKeys,
Object[] cellValues,
int[] cellRowIndices,
int[] cellColumnIndices) {
this.rowKeys = rowKeys;
this.columnKeys = columnKeys;
this.cellValues = cellValues;
this.cellRowIndices = cellRowIndices;
this.cellColumnIndices = cellColumnIndices;
}
static SerializedForm create(
ImmutableTable table, int[] cellRowIndices, int[] cellColumnIndices) {
return new SerializedForm(
table.rowKeySet().toArray(),
table.columnKeySet().toArray(),
table.values().toArray(),
cellRowIndices,
cellColumnIndices);
}
Object readResolve() {
if (cellValues.length == 0) {
return of();
}
if (cellValues.length == 1) {
return of(rowKeys[0], columnKeys[0], cellValues[0]);
}
ImmutableList.Builder> cellListBuilder =
new ImmutableList.Builder<>(cellValues.length);
for (int i = 0; i < cellValues.length; i++) {
cellListBuilder.add(
cellOf(rowKeys[cellRowIndices[i]], columnKeys[cellColumnIndices[i]], cellValues[i]));
}
return RegularImmutableTable.forOrderedComponents(
cellListBuilder.build(), ImmutableSet.copyOf(rowKeys), ImmutableSet.copyOf(columnKeys));
}
private static final long serialVersionUID = 0;
}
final Object writeReplace() {
return createSerializedForm();
}
}