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