001/*
002 * Copyright (C) 2008 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.collect;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.common.base.Objects;
021import com.google.errorprone.annotations.CanIgnoreReturnValue;
022import com.google.errorprone.annotations.CompatibleWith;
023import java.util.Collection;
024import java.util.Map;
025import java.util.Set;
026import org.checkerframework.checker.nullness.compatqual.NullableDecl;
027
028/**
029 * A collection that associates an ordered pair of keys, called a row key and a column key, with a
030 * single value. A table may be sparse, with only a small fraction of row key / column key pairs
031 * possessing a corresponding value.
032 *
033 * <p>The mappings corresponding to a given row key may be viewed as a {@link Map} whose keys are
034 * the columns. The reverse is also available, associating a column with a row key / value map. Note
035 * that, in some implementations, data access by column key may have fewer supported operations or
036 * worse performance than data access by row key.
037 *
038 * <p>The methods returning collections or maps always return views of the underlying table.
039 * Updating the table can change the contents of those collections, and updating the collections
040 * will change the table.
041 *
042 * <p>All methods that modify the table are optional, and the views returned by the table may or may
043 * not be modifiable. When modification isn't supported, those methods will throw an {@link
044 * UnsupportedOperationException}.
045 *
046 * <p>See the Guava User Guide article on <a href=
047 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table"> {@code Table}</a>.
048 *
049 * @author Jared Levy
050 * @param <R> the type of the table row keys
051 * @param <C> the type of the table column keys
052 * @param <V> the type of the mapped values
053 * @since 7.0
054 */
055@GwtCompatible
056public interface Table<R, C, V> {
057  // TODO(jlevy): Consider adding methods similar to ConcurrentMap methods.
058
059  // Accessors
060
061  /**
062   * Returns {@code true} if the table contains a mapping with the specified row and column keys.
063   *
064   * @param rowKey key of row to search for
065   * @param columnKey key of column to search for
066   */
067  boolean contains(
068      @NullableDecl @CompatibleWith("R") Object rowKey,
069      @NullableDecl @CompatibleWith("C") Object columnKey);
070
071  /**
072   * Returns {@code true} if the table contains a mapping with the specified row key.
073   *
074   * @param rowKey key of row to search for
075   */
076  boolean containsRow(@NullableDecl @CompatibleWith("R") Object rowKey);
077
078  /**
079   * Returns {@code true} if the table contains a mapping with the specified column.
080   *
081   * @param columnKey key of column to search for
082   */
083  boolean containsColumn(@NullableDecl @CompatibleWith("C") Object columnKey);
084
085  /**
086   * Returns {@code true} if the table contains a mapping with the specified value.
087   *
088   * @param value value to search for
089   */
090  boolean containsValue(@NullableDecl @CompatibleWith("V") Object value);
091
092  /**
093   * Returns the value corresponding to the given row and column keys, or {@code null} if no such
094   * mapping exists.
095   *
096   * @param rowKey key of row to search for
097   * @param columnKey key of column to search for
098   */
099  V get(
100      @NullableDecl @CompatibleWith("R") Object rowKey,
101      @NullableDecl @CompatibleWith("C") Object columnKey);
102
103  /** Returns {@code true} if the table contains no mappings. */
104  boolean isEmpty();
105
106  /** Returns the number of row key / column key / value mappings in the table. */
107  int size();
108
109  /**
110   * Compares the specified object with this table for equality. Two tables are equal when their
111   * cell views, as returned by {@link #cellSet}, are equal.
112   */
113  @Override
114  boolean equals(@NullableDecl Object obj);
115
116  /**
117   * Returns the hash code for this table. The hash code of a table is defined as the hash code of
118   * its cell view, as returned by {@link #cellSet}.
119   */
120  @Override
121  int hashCode();
122
123  // Mutators
124
125  /** Removes all mappings from the table. */
126  void clear();
127
128  /**
129   * Associates the specified value with the specified keys. If the table already contained a
130   * mapping for those keys, the old value is replaced with the specified value.
131   *
132   * @param rowKey row key that the value should be associated with
133   * @param columnKey column key that the value should be associated with
134   * @param value value to be associated with the specified keys
135   * @return the value previously associated with the keys, or {@code null} if no mapping existed
136   *     for the keys
137   */
138  @CanIgnoreReturnValue
139  @NullableDecl
140  V put(R rowKey, C columnKey, V value);
141
142  /**
143   * Copies all mappings from the specified table to this table. The effect is equivalent to calling
144   * {@link #put} with each row key / column key / value mapping in {@code table}.
145   *
146   * @param table the table to add to this table
147   */
148  void putAll(Table<? extends R, ? extends C, ? extends V> table);
149
150  /**
151   * Removes the mapping, if any, associated with the given keys.
152   *
153   * @param rowKey row key of mapping to be removed
154   * @param columnKey column key of mapping to be removed
155   * @return the value previously associated with the keys, or {@code null} if no such value existed
156   */
157  @CanIgnoreReturnValue
158  @NullableDecl
159  V remove(
160      @NullableDecl @CompatibleWith("R") Object rowKey,
161      @NullableDecl @CompatibleWith("C") Object columnKey);
162
163  // Views
164
165  /**
166   * Returns a view of all mappings that have the given row key. For each row key / column key /
167   * value mapping in the table with that row key, the returned map associates the column key with
168   * the value. If no mappings in the table have the provided row key, an empty map is returned.
169   *
170   * <p>Changes to the returned map will update the underlying table, and vice versa.
171   *
172   * @param rowKey key of row to search for in the table
173   * @return the corresponding map from column keys to values
174   */
175  Map<C, V> row(R rowKey);
176
177  /**
178   * Returns a view of all mappings that have the given column key. For each row key / column key /
179   * value mapping in the table with that column key, the returned map associates the row key with
180   * the value. If no mappings in the table have the provided column key, an empty map is returned.
181   *
182   * <p>Changes to the returned map will update the underlying table, and vice versa.
183   *
184   * @param columnKey key of column to search for in the table
185   * @return the corresponding map from row keys to values
186   */
187  Map<R, V> column(C columnKey);
188
189  /**
190   * Returns a set of all row key / column key / value triplets. Changes to the returned set will
191   * update the underlying table, and vice versa. The cell set does not support the {@code add} or
192   * {@code addAll} methods.
193   *
194   * @return set of table cells consisting of row key / column key / value triplets
195   */
196  Set<Cell<R, C, V>> cellSet();
197
198  /**
199   * Returns a set of row keys that have one or more values in the table. Changes to the set will
200   * update the underlying table, and vice versa.
201   *
202   * @return set of row keys
203   */
204  Set<R> rowKeySet();
205
206  /**
207   * Returns a set of column keys that have one or more values in the table. Changes to the set will
208   * update the underlying table, and vice versa.
209   *
210   * @return set of column keys
211   */
212  Set<C> columnKeySet();
213
214  /**
215   * Returns a collection of all values, which may contain duplicates. Changes to the returned
216   * collection will update the underlying table, and vice versa.
217   *
218   * @return collection of values
219   */
220  Collection<V> values();
221
222  /**
223   * Returns a view that associates each row key with the corresponding map from column keys to
224   * values. Changes to the returned map will update this table. The returned map does not support
225   * {@code put()} or {@code putAll()}, or {@code setValue()} on its entries.
226   *
227   * <p>In contrast, the maps returned by {@code rowMap().get()} have the same behavior as those
228   * returned by {@link #row}. Those maps may support {@code setValue()}, {@code put()}, and {@code
229   * putAll()}.
230   *
231   * @return a map view from each row key to a secondary map from column keys to values
232   */
233  Map<R, Map<C, V>> rowMap();
234
235  /**
236   * Returns a view that associates each column key with the corresponding map from row keys to
237   * values. Changes to the returned map will update this table. The returned map does not support
238   * {@code put()} or {@code putAll()}, or {@code setValue()} on its entries.
239   *
240   * <p>In contrast, the maps returned by {@code columnMap().get()} have the same behavior as those
241   * returned by {@link #column}. Those maps may support {@code setValue()}, {@code put()}, and
242   * {@code putAll()}.
243   *
244   * @return a map view from each column key to a secondary map from row keys to values
245   */
246  Map<C, Map<R, V>> columnMap();
247
248  /**
249   * Row key / column key / value triplet corresponding to a mapping in a table.
250   *
251   * @since 7.0
252   */
253  interface Cell<R, C, V> {
254    /** Returns the row key of this cell. */
255    @NullableDecl
256    R getRowKey();
257
258    /** Returns the column key of this cell. */
259    @NullableDecl
260    C getColumnKey();
261
262    /** Returns the value of this cell. */
263    @NullableDecl
264    V getValue();
265
266    /**
267     * Compares the specified object with this cell for equality. Two cells are equal when they have
268     * equal row keys, column keys, and values.
269     */
270    @Override
271    boolean equals(@NullableDecl Object obj);
272
273    /**
274     * Returns the hash code of this cell.
275     *
276     * <p>The hash code of a table cell is equal to {@link Objects#hashCode}{@code (e.getRowKey(),
277     * e.getColumnKey(), e.getValue())}.
278     */
279    @Override
280    int hashCode();
281  }
282}