|
The Table.java Java example source code
/*
* Copyright (C) 2008 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 com.google.common.annotations.GwtCompatible;
import com.google.common.base.Objects;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import javax.annotation.Nullable;
/**
* A collection that associates an ordered pair of keys, called a row key and a
* column key, with a single value. A table may be sparse, with only a small
* fraction of row key / column key pairs possessing a corresponding value.
*
* <p>The mappings corresponding to a given row key may be viewed as a {@link
* Map} whose keys are the columns. The reverse is also available, associating a
* column with a row key / value map. Note that, in some implementations, data
* access by column key may have fewer supported operations or worse performance
* than data access by row key.
*
* <p>The methods returning collections or maps always return views of the
* underlying table. Updating the table can change the contents of those
* collections, and updating the collections will change the table.
*
* <p>All methods that modify the table are optional, and the views returned by
* the table may or may not be modifiable. When modification isn't supported,
* those methods will throw an {@link UnsupportedOperationException}.
*
* <p>See the Guava User Guide article on cellSet();
/**
* 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.
*
* @return set of row keys
*/
Set<R> rowKeySet();
/**
* 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.
*
* @return set of column keys
*/
Set<C> columnKeySet();
/**
* Returns a collection of all values, which may contain duplicates. Changes
* to the returned collection will update the underlying table, and vice
* versa.
*
* @return collection of values
*/
Collection<V> values();
/**
* 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 {@code put()} or {@code putAll()}, or
* {@code setValue()} on its entries.
*
* <p>In contrast, the maps returned by {@code rowMap().get()} have the same
* behavior as those returned by {@link #row}. Those maps may support {@code
* setValue()}, {@code put()}, and {@code putAll()}.
*
* @return a map view from each row key to a secondary map from column keys to
* values
*/
Map<R, Map rowMap();
/**
* 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 {@code put()} or {@code putAll()},
* or {@code setValue()} on its entries.
*
* <p>In contrast, the maps returned by {@code columnMap().get()} have the
* same behavior as those returned by {@link #column}. Those maps may support
* {@code setValue()}, {@code put()}, and {@code putAll()}.
*
* @return a map view from each column key to a secondary map from row keys to
* values
*/
Map<C, Map columnMap();
/**
* Row key / column key / value triplet corresponding to a mapping in a table.
*
* @since 7.0
*/
interface Cell<R, C, V> {
/**
* Returns the row key of this cell.
*/
@Nullable
R getRowKey();
/**
* Returns the column key of this cell.
*/
@Nullable
C getColumnKey();
/**
* Returns the value of this cell.
*/
@Nullable
V getValue();
/**
* Compares the specified object with this cell for equality. Two cells are
* equal when they have equal row keys, column keys, and values.
*/
@Override
boolean equals(@Nullable Object obj);
/**
* Returns the hash code of this cell.
*
* <p>The hash code of a table cell is equal to {@link
* Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
*/
@Override
int hashCode();
}
}
|