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.Objects;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import javax.annotation.Nullable;
/**
* An immutable {@link Table} with reliable user-specified iteration order.
* Does not permit null keys or values.
*
* Note: Although this class is not final, it cannot be subclassed as
* it has no public or protected constructors. Thus, instances of this class are
* guaranteed to be immutable.
*
*
See the Guava User Guide article on
* immutable collections.
*
* @author Gregory Kick
* @since 11.0
*/
@GwtCompatible
// TODO(gak): make serializable
public abstract class ImmutableTable extends AbstractTable {
private static final ImmutableTable EMPTY
= new SparseImmutableTable(
ImmutableList.>of(),
ImmutableSet.of(), ImmutableSet.of());
/** Returns an empty immutable table. */
@SuppressWarnings("unchecked")
public static ImmutableTable of() {
return (ImmutableTable) 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 {
int size = table.size();
switch (size) {
case 0:
return of();
case 1:
Cell onlyCell
= Iterables.getOnlyElement(table.cellSet());
return ImmutableTable.of(onlyCell.getRowKey(),
onlyCell.getColumnKey(), onlyCell.getValue());
default:
ImmutableSet.Builder> cellSetBuilder
= ImmutableSet.builder();
for (Cell cell :
table.cellSet()) {
/*
* Must cast to be able to create a Cell rather than a
* Cell
*/
cellSetBuilder.add(cellOf((R) cell.getRowKey(),
(C) cell.getColumnKey(), (V) cell.getValue()));
}
return RegularImmutableTable.forCells(cellSetBuilder.build());
}
}
}
/**
* Returns a new builder. The generated builder is equivalent to the builder
* created by the {@link 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), checkNotNull(columnKey),
checkNotNull(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
*/
public static final class Builder {
private final List> cells = Lists.newArrayList();
private Comparator rowComparator;
private 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.
*/
public Builder orderRowsBy(Comparator rowComparator) {
this.rowComparator = checkNotNull(rowComparator);
return this;
}
/**
* Specifies the ordering of the generated table's columns.
*/
public Builder orderColumnsBy(
Comparator columnComparator) {
this.columnComparator = checkNotNull(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.
*/
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.
*/
public Builder put(
Cell cell) {
if (cell instanceof Tables.ImmutableCell) {
checkNotNull(cell.getRowKey());
checkNotNull(cell.getColumnKey());
checkNotNull(cell.getValue());
@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
*/
public Builder putAll(
Table table) {
for (Cell cell : table.cellSet()) {
put(cell);
}
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
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);
return Objects.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);
return Objects.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.
*/
@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.
*/
@Deprecated @Override public final V remove(Object rowKey, Object columnKey) {
throw new UnsupportedOperationException();
}
}