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