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