1 /*
2 * Copyright (C) 2008 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.common.collect;
18
19 import static com.google.common.collect.CollectPreconditions.checkNonnegative;
20
21 import com.google.common.annotations.GwtCompatible;
22 import com.google.common.base.Supplier;
23 import com.google.errorprone.annotations.CanIgnoreReturnValue;
24 import java.io.Serializable;
25 import java.util.LinkedHashMap;
26 import java.util.Map;
27 import org.checkerframework.checker.nullness.qual.Nullable;
28
29 /**
30 * Implementation of {@link Table} using linked hash tables. This guarantees predictable iteration
31 * order of the various views.
32 *
33 * <p>The views returned by {@link #column}, {@link #columnKeySet()}, and {@link #columnMap()} have
34 * iterators that don't support {@code remove()}. Otherwise, all optional operations are supported.
35 * Null row keys, columns keys, and values are not supported.
36 *
37 * <p>Lookups by row key are often faster than lookups by column key, because the data is stored in
38 * a {@code Map<R, Map<C, V>>}. A method call like {@code column(columnKey).get(rowKey)} still runs
39 * quickly, since the row key is provided. However, {@code column(columnKey).size()} takes longer,
40 * since an iteration across all row keys occurs.
41 *
42 * <p>Note that this implementation is not synchronized. If multiple threads access this table
43 * concurrently and one of the threads modifies the table, it must be synchronized externally.
44 *
45 * <p>See the Guava User Guide article on <a href=
46 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table"> {@code Table}</a>.
47 *
48 * @author Jared Levy
49 * @since 7.0
50 */
51 @GwtCompatible(serializable = true)
52 public class HashBasedTable<R, C, V> extends StandardTable<R, C, V> {
53 private static class Factory<C, V> implements Supplier<Map<C, V>>, Serializable {
54 final int expectedSize;
55
56 Factory(int expectedSize) {
57 this.expectedSize = expectedSize;
58 }
59
60 @Override
61 public Map<C, V> get() {
62 return Maps.newLinkedHashMapWithExpectedSize(expectedSize);
63 }
64
65 private static final long serialVersionUID = 0;
66 }
67
68 /** Creates an empty {@code HashBasedTable}. */
69 public static <R, C, V> HashBasedTable<R, C, V> create() {
70 return new HashBasedTable<>(new LinkedHashMap<R, Map<C, V>>(), new Factory<C, V>(0));
71 }
72
73 /**
74 * Creates an empty {@code HashBasedTable} with the specified map sizes.
75 *
76 * @param expectedRows the expected number of distinct row keys
77 * @param expectedCellsPerRow the expected number of column key / value mappings in each row
78 * @throws IllegalArgumentException if {@code expectedRows} or {@code expectedCellsPerRow} is
79 * negative
80 */
81 public static <R, C, V> HashBasedTable<R, C, V> create(
82 int expectedRows, int expectedCellsPerRow) {
83 checkNonnegative(expectedCellsPerRow, "expectedCellsPerRow");
84 Map<R, Map<C, V>> backingMap = Maps.newLinkedHashMapWithExpectedSize(expectedRows);
85 return new HashBasedTable<>(backingMap, new Factory<C, V>(expectedCellsPerRow));
86 }
87
88 /**
89 * Creates a {@code HashBasedTable} with the same mappings as the specified table.
90 *
91 * @param table the table to copy
92 * @throws NullPointerException if any of the row keys, column keys, or values in {@code table} is
93 * null
94 */
95 public static <R, C, V> HashBasedTable<R, C, V> create(
96 Table<? extends R, ? extends C, ? extends V> table) {
97 HashBasedTable<R, C, V> result = create();
98 result.putAll(table);
99 return result;
100 }
101
102 HashBasedTable(Map<R, Map<C, V>> backingMap, Factory<C, V> factory) {
103 super(backingMap, factory);
104 }
105
106 // Overriding so NullPointerTester test passes.
107
108 @Override
109 public boolean contains(@Nullable Object rowKey, @Nullable Object columnKey) {
110 return super.contains(rowKey, columnKey);
111 }
112
113 @Override
114 public boolean containsColumn(@Nullable Object columnKey) {
115 return super.containsColumn(columnKey);
116 }
117
118 @Override
119 public boolean containsRow(@Nullable Object rowKey) {
120 return super.containsRow(rowKey);
121 }
122
123 @Override
124 public boolean containsValue(@Nullable Object value) {
125 return super.containsValue(value);
126 }
127
128 @Override
129 public V get(@Nullable Object rowKey, @Nullable Object columnKey) {
130 return super.get(rowKey, columnKey);
131 }
132
133 @Override
134 public boolean equals(@Nullable Object obj) {
135 return super.equals(obj);
136 }
137
138 @CanIgnoreReturnValue
139 @Override
140 public V remove(@Nullable Object rowKey, @Nullable Object columnKey) {
141 return super.remove(rowKey, columnKey);
142 }
143
144 private static final long serialVersionUID = 0;
145 }