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