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