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