All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.collect.ImmutableTable Maven / Gradle / Ivy

There is a newer version: 1.45.6
Show newest version
/*
 * 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.errorprone.annotations.CanIgnoreReturnValue;
import com.google.errorprone.annotations.DoNotCall;
import com.google.errorprone.annotations.DoNotMock;
import java.io.Serializable;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import org.checkerframework.checker.nullness.compatqual.NullableDecl;

/**
 * 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 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()); } } 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(); @NullableDecl private Comparator rowComparator; @NullableDecl 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. */ @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; } @CanIgnoreReturnValue 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 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(@NullableDecl Object rowKey, @NullableDecl Object columnKey) { return get(rowKey, columnKey) != null; } @Override public boolean containsValue(@NullableDecl Object value) { return values().contains(value); } /** * Guaranteed to throw an exception and leave the table unmodified. * * @throws UnsupportedOperationException always * @deprecated Unsupported operation. */ @Deprecated @Override @DoNotCall("Always throws UnsupportedOperationException") 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 @DoNotCall("Always throws UnsupportedOperationException") 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 @DoNotCall("Always throws UnsupportedOperationException") 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 @DoNotCall("Always throws UnsupportedOperationException") 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(); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy