001/*
002 * Copyright (C) 2009 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 static com.google.common.base.Preconditions.checkArgument;
020import static com.google.common.base.Preconditions.checkElementIndex;
021import static com.google.common.base.Preconditions.checkNotNull;
022
023import com.google.common.annotations.Beta;
024import com.google.common.annotations.GwtCompatible;
025import com.google.common.annotations.GwtIncompatible;
026import com.google.common.base.Objects;
027import com.google.common.collect.Maps.IteratorBasedAbstractMap;
028import com.google.errorprone.annotations.CanIgnoreReturnValue;
029import com.google.j2objc.annotations.WeakOuter;
030import java.io.Serializable;
031import java.lang.reflect.Array;
032import java.util.Arrays;
033import java.util.Collection;
034import java.util.Iterator;
035import java.util.Map;
036import java.util.Set;
037import org.checkerframework.checker.nullness.compatqual.NullableDecl;
038
039/**
040 * Fixed-size {@link Table} implementation backed by a two-dimensional array.
041 *
042 * <p>The allowed row and column keys must be supplied when the table is created. The table always
043 * contains a mapping for every row key / column pair. The value corresponding to a given row and
044 * column is null unless another value is provided.
045 *
046 * <p>The table's size is constant: the product of the number of supplied row keys and the number of
047 * supplied column keys. The {@code remove} and {@code clear} methods are not supported by the table
048 * or its views. The {@link #erase} and {@link #eraseAll} methods may be used instead.
049 *
050 * <p>The ordering of the row and column keys provided when the table is constructed determines the
051 * iteration ordering across rows and columns in the table's views. None of the view iterators
052 * support {@link Iterator#remove}. If the table is modified after an iterator is created, the
053 * iterator remains valid.
054 *
055 * <p>This class requires less memory than the {@link HashBasedTable} and {@link TreeBasedTable}
056 * implementations, except when the table is sparse.
057 *
058 * <p>Null row keys or column keys are not permitted.
059 *
060 * <p>This class provides methods involving the underlying array structure, where the array indices
061 * correspond to the position of a row or column in the lists of allowed keys and values. See the
062 * {@link #at}, {@link #set}, {@link #toArray}, {@link #rowKeyList}, and {@link #columnKeyList}
063 * methods for more details.
064 *
065 * <p>Note that this implementation is not synchronized. If multiple threads access the same cell of
066 * an {@code ArrayTable} concurrently and one of the threads modifies its value, there is no
067 * guarantee that the new value will be fully visible to the other threads. To guarantee that
068 * modifications are visible, synchronize access to the table. Unlike other {@code Table}
069 * implementations, synchronization is unnecessary between a thread that writes to one cell and a
070 * thread that reads from another.
071 *
072 * <p>See the Guava User Guide article on <a href=
073 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#table"> {@code Table}</a>.
074 *
075 * @author Jared Levy
076 * @since 10.0
077 */
078@Beta
079@GwtCompatible(emulated = true)
080public final class ArrayTable<R, C, V> extends AbstractTable<R, C, V> implements Serializable {
081
082  /**
083   * Creates an {@code ArrayTable} filled with {@code null}.
084   *
085   * @param rowKeys row keys that may be stored in the generated table
086   * @param columnKeys column keys that may be stored in the generated table
087   * @throws NullPointerException if any of the provided keys is null
088   * @throws IllegalArgumentException if {@code rowKeys} or {@code columnKeys} contains duplicates
089   *     or if exactly one of {@code rowKeys} or {@code columnKeys} is empty.
090   */
091  public static <R, C, V> ArrayTable<R, C, V> create(
092      Iterable<? extends R> rowKeys, Iterable<? extends C> columnKeys) {
093    return new ArrayTable<>(rowKeys, columnKeys);
094  }
095
096  /*
097   * TODO(jlevy): Add factory methods taking an Enum class, instead of an
098   * iterable, to specify the allowed row keys and/or column keys. Note that
099   * custom serialization logic is needed to support different enum sizes during
100   * serialization and deserialization.
101   */
102
103  /**
104   * Creates an {@code ArrayTable} with the mappings in the provided table.
105   *
106   * <p>If {@code table} includes a mapping with row key {@code r} and a separate mapping with
107   * column key {@code c}, the returned table contains a mapping with row key {@code r} and column
108   * key {@code c}. If that row key / column key pair in not in {@code table}, the pair maps to
109   * {@code null} in the generated table.
110   *
111   * <p>The returned table allows subsequent {@code put} calls with the row keys in {@code
112   * table.rowKeySet()} and the column keys in {@code table.columnKeySet()}. Calling {@link #put}
113   * with other keys leads to an {@code IllegalArgumentException}.
114   *
115   * <p>The ordering of {@code table.rowKeySet()} and {@code table.columnKeySet()} determines the
116   * row and column iteration ordering of the returned table.
117   *
118   * @throws NullPointerException if {@code table} has a null key
119   */
120  public static <R, C, V> ArrayTable<R, C, V> create(Table<R, C, V> table) {
121    return (table instanceof ArrayTable<?, ?, ?>)
122        ? new ArrayTable<R, C, V>((ArrayTable<R, C, V>) table)
123        : new ArrayTable<R, C, V>(table);
124  }
125
126  private final ImmutableList<R> rowList;
127  private final ImmutableList<C> columnList;
128
129  // TODO(jlevy): Add getters returning rowKeyToIndex and columnKeyToIndex?
130  private final ImmutableMap<R, Integer> rowKeyToIndex;
131  private final ImmutableMap<C, Integer> columnKeyToIndex;
132  private final V[][] array;
133
134  private ArrayTable(Iterable<? extends R> rowKeys, Iterable<? extends C> columnKeys) {
135    this.rowList = ImmutableList.copyOf(rowKeys);
136    this.columnList = ImmutableList.copyOf(columnKeys);
137    checkArgument(rowList.isEmpty() == columnList.isEmpty());
138
139    /*
140     * TODO(jlevy): Support only one of rowKey / columnKey being empty? If we
141     * do, when columnKeys is empty but rowKeys isn't, rowKeyList() can contain
142     * elements but rowKeySet() will be empty and containsRow() won't
143     * acknolwedge them.
144     */
145    rowKeyToIndex = Maps.indexMap(rowList);
146    columnKeyToIndex = Maps.indexMap(columnList);
147
148    @SuppressWarnings("unchecked")
149    V[][] tmpArray = (V[][]) new Object[rowList.size()][columnList.size()];
150    array = tmpArray;
151    // Necessary because in GWT the arrays are initialized with "undefined" instead of null.
152    eraseAll();
153  }
154
155  private ArrayTable(Table<R, C, V> table) {
156    this(table.rowKeySet(), table.columnKeySet());
157    putAll(table);
158  }
159
160  private ArrayTable(ArrayTable<R, C, V> table) {
161    rowList = table.rowList;
162    columnList = table.columnList;
163    rowKeyToIndex = table.rowKeyToIndex;
164    columnKeyToIndex = table.columnKeyToIndex;
165    @SuppressWarnings("unchecked")
166    V[][] copy = (V[][]) new Object[rowList.size()][columnList.size()];
167    array = copy;
168    for (int i = 0; i < rowList.size(); i++) {
169      System.arraycopy(table.array[i], 0, copy[i], 0, table.array[i].length);
170    }
171  }
172
173  private abstract static class ArrayMap<K, V> extends IteratorBasedAbstractMap<K, V> {
174    private final ImmutableMap<K, Integer> keyIndex;
175
176    private ArrayMap(ImmutableMap<K, Integer> keyIndex) {
177      this.keyIndex = keyIndex;
178    }
179
180    @Override
181    public Set<K> keySet() {
182      return keyIndex.keySet();
183    }
184
185    K getKey(int index) {
186      return keyIndex.keySet().asList().get(index);
187    }
188
189    abstract String getKeyRole();
190
191    @NullableDecl
192    abstract V getValue(int index);
193
194    @NullableDecl
195    abstract V setValue(int index, V newValue);
196
197    @Override
198    public int size() {
199      return keyIndex.size();
200    }
201
202    @Override
203    public boolean isEmpty() {
204      return keyIndex.isEmpty();
205    }
206
207    Entry<K, V> getEntry(final int index) {
208      checkElementIndex(index, size());
209      return new AbstractMapEntry<K, V>() {
210        @Override
211        public K getKey() {
212          return ArrayMap.this.getKey(index);
213        }
214
215        @Override
216        public V getValue() {
217          return ArrayMap.this.getValue(index);
218        }
219
220        @Override
221        public V setValue(V value) {
222          return ArrayMap.this.setValue(index, value);
223        }
224      };
225    }
226
227    @Override
228    Iterator<Entry<K, V>> entryIterator() {
229      return new AbstractIndexedListIterator<Entry<K, V>>(size()) {
230        @Override
231        protected Entry<K, V> get(final int index) {
232          return getEntry(index);
233        }
234      };
235    }
236
237    // TODO(lowasser): consider an optimized values() implementation
238
239    @Override
240    public boolean containsKey(@NullableDecl Object key) {
241      return keyIndex.containsKey(key);
242    }
243
244    @Override
245    public V get(@NullableDecl Object key) {
246      Integer index = keyIndex.get(key);
247      if (index == null) {
248        return null;
249      } else {
250        return getValue(index);
251      }
252    }
253
254    @Override
255    public V put(K key, V value) {
256      Integer index = keyIndex.get(key);
257      if (index == null) {
258        throw new IllegalArgumentException(
259            getKeyRole() + " " + key + " not in " + keyIndex.keySet());
260      }
261      return setValue(index, value);
262    }
263
264    @Override
265    public V remove(Object key) {
266      throw new UnsupportedOperationException();
267    }
268
269    @Override
270    public void clear() {
271      throw new UnsupportedOperationException();
272    }
273  }
274
275  /**
276   * Returns, as an immutable list, the row keys provided when the table was constructed, including
277   * those that are mapped to null values only.
278   */
279  public ImmutableList<R> rowKeyList() {
280    return rowList;
281  }
282
283  /**
284   * Returns, as an immutable list, the column keys provided when the table was constructed,
285   * including those that are mapped to null values only.
286   */
287  public ImmutableList<C> columnKeyList() {
288    return columnList;
289  }
290
291  /**
292   * Returns the value corresponding to the specified row and column indices. The same value is
293   * returned by {@code get(rowKeyList().get(rowIndex), columnKeyList().get(columnIndex))}, but this
294   * method runs more quickly.
295   *
296   * @param rowIndex position of the row key in {@link #rowKeyList()}
297   * @param columnIndex position of the row key in {@link #columnKeyList()}
298   * @return the value with the specified row and column
299   * @throws IndexOutOfBoundsException if either index is negative, {@code rowIndex} is greater than
300   *     or equal to the number of allowed row keys, or {@code columnIndex} is greater than or equal
301   *     to the number of allowed column keys
302   */
303  public V at(int rowIndex, int columnIndex) {
304    // In GWT array access never throws IndexOutOfBoundsException.
305    checkElementIndex(rowIndex, rowList.size());
306    checkElementIndex(columnIndex, columnList.size());
307    return array[rowIndex][columnIndex];
308  }
309
310  /**
311   * Associates {@code value} with the specified row and column indices. The logic {@code
312   * put(rowKeyList().get(rowIndex), columnKeyList().get(columnIndex), value)} has the same
313   * behavior, but this method runs more quickly.
314   *
315   * @param rowIndex position of the row key in {@link #rowKeyList()}
316   * @param columnIndex position of the row key in {@link #columnKeyList()}
317   * @param value value to store in the table
318   * @return the previous value with the specified row and column
319   * @throws IndexOutOfBoundsException if either index is negative, {@code rowIndex} is greater than
320   *     or equal to the number of allowed row keys, or {@code columnIndex} is greater than or equal
321   *     to the number of allowed column keys
322   */
323  @CanIgnoreReturnValue
324  public V set(int rowIndex, int columnIndex, @NullableDecl V value) {
325    // In GWT array access never throws IndexOutOfBoundsException.
326    checkElementIndex(rowIndex, rowList.size());
327    checkElementIndex(columnIndex, columnList.size());
328    V oldValue = array[rowIndex][columnIndex];
329    array[rowIndex][columnIndex] = value;
330    return oldValue;
331  }
332
333  /**
334   * Returns a two-dimensional array with the table contents. The row and column indices correspond
335   * to the positions of the row and column in the iterables provided during table construction. If
336   * the table lacks a mapping for a given row and column, the corresponding array element is null.
337   *
338   * <p>Subsequent table changes will not modify the array, and vice versa.
339   *
340   * @param valueClass class of values stored in the returned array
341   */
342  @GwtIncompatible // reflection
343  public V[][] toArray(Class<V> valueClass) {
344    @SuppressWarnings("unchecked") // TODO: safe?
345    V[][] copy = (V[][]) Array.newInstance(valueClass, rowList.size(), columnList.size());
346    for (int i = 0; i < rowList.size(); i++) {
347      System.arraycopy(array[i], 0, copy[i], 0, array[i].length);
348    }
349    return copy;
350  }
351
352  /**
353   * Not supported. Use {@link #eraseAll} instead.
354   *
355   * @throws UnsupportedOperationException always
356   * @deprecated Use {@link #eraseAll}
357   */
358  @Override
359  @Deprecated
360  public void clear() {
361    throw new UnsupportedOperationException();
362  }
363
364  /** Associates the value {@code null} with every pair of allowed row and column keys. */
365  public void eraseAll() {
366    for (V[] row : array) {
367      Arrays.fill(row, null);
368    }
369  }
370
371  /**
372   * Returns {@code true} if the provided keys are among the keys provided when the table was
373   * constructed.
374   */
375  @Override
376  public boolean contains(@NullableDecl Object rowKey, @NullableDecl Object columnKey) {
377    return containsRow(rowKey) && containsColumn(columnKey);
378  }
379
380  /**
381   * Returns {@code true} if the provided column key is among the column keys provided when the
382   * table was constructed.
383   */
384  @Override
385  public boolean containsColumn(@NullableDecl Object columnKey) {
386    return columnKeyToIndex.containsKey(columnKey);
387  }
388
389  /**
390   * Returns {@code true} if the provided row key is among the row keys provided when the table was
391   * constructed.
392   */
393  @Override
394  public boolean containsRow(@NullableDecl Object rowKey) {
395    return rowKeyToIndex.containsKey(rowKey);
396  }
397
398  @Override
399  public boolean containsValue(@NullableDecl Object value) {
400    for (V[] row : array) {
401      for (V element : row) {
402        if (Objects.equal(value, element)) {
403          return true;
404        }
405      }
406    }
407    return false;
408  }
409
410  @Override
411  public V get(@NullableDecl Object rowKey, @NullableDecl Object columnKey) {
412    Integer rowIndex = rowKeyToIndex.get(rowKey);
413    Integer columnIndex = columnKeyToIndex.get(columnKey);
414    return (rowIndex == null || columnIndex == null) ? null : at(rowIndex, columnIndex);
415  }
416
417  /**
418   * Returns {@code true} if {@code rowKeyList().size == 0} or {@code columnKeyList().size() == 0}.
419   */
420  @Override
421  public boolean isEmpty() {
422    return rowList.isEmpty() || columnList.isEmpty();
423  }
424
425  /**
426   * {@inheritDoc}
427   *
428   * @throws IllegalArgumentException if {@code rowKey} is not in {@link #rowKeySet()} or {@code
429   *     columnKey} is not in {@link #columnKeySet()}.
430   */
431  @CanIgnoreReturnValue
432  @Override
433  public V put(R rowKey, C columnKey, @NullableDecl V value) {
434    checkNotNull(rowKey);
435    checkNotNull(columnKey);
436    Integer rowIndex = rowKeyToIndex.get(rowKey);
437    checkArgument(rowIndex != null, "Row %s not in %s", rowKey, rowList);
438    Integer columnIndex = columnKeyToIndex.get(columnKey);
439    checkArgument(columnIndex != null, "Column %s not in %s", columnKey, columnList);
440    return set(rowIndex, columnIndex, value);
441  }
442
443  /*
444   * TODO(jlevy): Consider creating a merge() method, similar to putAll() but
445   * copying non-null values only.
446   */
447
448  /**
449   * {@inheritDoc}
450   *
451   * <p>If {@code table} is an {@code ArrayTable}, its null values will be stored in this table,
452   * possibly replacing values that were previously non-null.
453   *
454   * @throws NullPointerException if {@code table} has a null key
455   * @throws IllegalArgumentException if any of the provided table's row keys or column keys is not
456   *     in {@link #rowKeySet()} or {@link #columnKeySet()}
457   */
458  @Override
459  public void putAll(Table<? extends R, ? extends C, ? extends V> table) {
460    super.putAll(table);
461  }
462
463  /**
464   * Not supported. Use {@link #erase} instead.
465   *
466   * @throws UnsupportedOperationException always
467   * @deprecated Use {@link #erase}
468   */
469  @CanIgnoreReturnValue
470  @Override
471  @Deprecated
472  public V remove(Object rowKey, Object columnKey) {
473    throw new UnsupportedOperationException();
474  }
475
476  /**
477   * Associates the value {@code null} with the specified keys, assuming both keys are valid. If
478   * either key is null or isn't among the keys provided during construction, this method has no
479   * effect.
480   *
481   * <p>This method is equivalent to {@code put(rowKey, columnKey, null)} when both provided keys
482   * are valid.
483   *
484   * @param rowKey row key of mapping to be erased
485   * @param columnKey column key of mapping to be erased
486   * @return the value previously associated with the keys, or {@code null} if no mapping existed
487   *     for the keys
488   */
489  @CanIgnoreReturnValue
490  public V erase(@NullableDecl Object rowKey, @NullableDecl Object columnKey) {
491    Integer rowIndex = rowKeyToIndex.get(rowKey);
492    Integer columnIndex = columnKeyToIndex.get(columnKey);
493    if (rowIndex == null || columnIndex == null) {
494      return null;
495    }
496    return set(rowIndex, columnIndex, null);
497  }
498
499  // TODO(jlevy): Add eraseRow and eraseColumn methods?
500
501  @Override
502  public int size() {
503    return rowList.size() * columnList.size();
504  }
505
506  /**
507   * Returns an unmodifiable set of all row key / column key / value triplets. Changes to the table
508   * will update the returned set.
509   *
510   * <p>The returned set's iterator traverses the mappings with the first row key, the mappings with
511   * the second row key, and so on.
512   *
513   * <p>The value in the returned cells may change if the table subsequently changes.
514   *
515   * @return set of table cells consisting of row key / column key / value triplets
516   */
517  @Override
518  public Set<Cell<R, C, V>> cellSet() {
519    return super.cellSet();
520  }
521
522  @Override
523  Iterator<Cell<R, C, V>> cellIterator() {
524    return new AbstractIndexedListIterator<Cell<R, C, V>>(size()) {
525      @Override
526      protected Cell<R, C, V> get(final int index) {
527        return getCell(index);
528      }
529    };
530  }
531
532  private Cell<R, C, V> getCell(final int index) {
533    return new Tables.AbstractCell<R, C, V>() {
534      final int rowIndex = index / columnList.size();
535      final int columnIndex = index % columnList.size();
536
537      @Override
538      public R getRowKey() {
539        return rowList.get(rowIndex);
540      }
541
542      @Override
543      public C getColumnKey() {
544        return columnList.get(columnIndex);
545      }
546
547      @Override
548      public V getValue() {
549        return at(rowIndex, columnIndex);
550      }
551    };
552  }
553
554  private V getValue(int index) {
555    int rowIndex = index / columnList.size();
556    int columnIndex = index % columnList.size();
557    return at(rowIndex, columnIndex);
558  }
559
560  /**
561   * Returns a view of all mappings that have the given column key. If the column key isn't in
562   * {@link #columnKeySet()}, an empty immutable map is returned.
563   *
564   * <p>Otherwise, for each row key in {@link #rowKeySet()}, the returned map associates the row key
565   * with the corresponding value in the table. Changes to the returned map will update the
566   * underlying table, and vice versa.
567   *
568   * @param columnKey key of column to search for in the table
569   * @return the corresponding map from row keys to values
570   */
571  @Override
572  public Map<R, V> column(C columnKey) {
573    checkNotNull(columnKey);
574    Integer columnIndex = columnKeyToIndex.get(columnKey);
575    return (columnIndex == null) ? ImmutableMap.<R, V>of() : new Column(columnIndex);
576  }
577
578  private class Column extends ArrayMap<R, V> {
579    final int columnIndex;
580
581    Column(int columnIndex) {
582      super(rowKeyToIndex);
583      this.columnIndex = columnIndex;
584    }
585
586    @Override
587    String getKeyRole() {
588      return "Row";
589    }
590
591    @Override
592    V getValue(int index) {
593      return at(index, columnIndex);
594    }
595
596    @Override
597    V setValue(int index, V newValue) {
598      return set(index, columnIndex, newValue);
599    }
600  }
601
602  /**
603   * Returns an immutable set of the valid column keys, including those that are associated with
604   * null values only.
605   *
606   * @return immutable set of column keys
607   */
608  @Override
609  public ImmutableSet<C> columnKeySet() {
610    return columnKeyToIndex.keySet();
611  }
612
613  @NullableDecl private transient ColumnMap columnMap;
614
615  @Override
616  public Map<C, Map<R, V>> columnMap() {
617    ColumnMap map = columnMap;
618    return (map == null) ? columnMap = new ColumnMap() : map;
619  }
620
621  @WeakOuter
622  private class ColumnMap extends ArrayMap<C, Map<R, V>> {
623    private ColumnMap() {
624      super(columnKeyToIndex);
625    }
626
627    @Override
628    String getKeyRole() {
629      return "Column";
630    }
631
632    @Override
633    Map<R, V> getValue(int index) {
634      return new Column(index);
635    }
636
637    @Override
638    Map<R, V> setValue(int index, Map<R, V> newValue) {
639      throw new UnsupportedOperationException();
640    }
641
642    @Override
643    public Map<R, V> put(C key, Map<R, V> value) {
644      throw new UnsupportedOperationException();
645    }
646  }
647
648  /**
649   * Returns a view of all mappings that have the given row key. If the row key isn't in {@link
650   * #rowKeySet()}, an empty immutable map is returned.
651   *
652   * <p>Otherwise, for each column key in {@link #columnKeySet()}, the returned map associates the
653   * column key with the corresponding value in the table. Changes to the returned map will update
654   * the underlying table, and vice versa.
655   *
656   * @param rowKey key of row to search for in the table
657   * @return the corresponding map from column keys to values
658   */
659  @Override
660  public Map<C, V> row(R rowKey) {
661    checkNotNull(rowKey);
662    Integer rowIndex = rowKeyToIndex.get(rowKey);
663    return (rowIndex == null) ? ImmutableMap.<C, V>of() : new Row(rowIndex);
664  }
665
666  private class Row extends ArrayMap<C, V> {
667    final int rowIndex;
668
669    Row(int rowIndex) {
670      super(columnKeyToIndex);
671      this.rowIndex = rowIndex;
672    }
673
674    @Override
675    String getKeyRole() {
676      return "Column";
677    }
678
679    @Override
680    V getValue(int index) {
681      return at(rowIndex, index);
682    }
683
684    @Override
685    V setValue(int index, V newValue) {
686      return set(rowIndex, index, newValue);
687    }
688  }
689
690  /**
691   * Returns an immutable set of the valid row keys, including those that are associated with null
692   * values only.
693   *
694   * @return immutable set of row keys
695   */
696  @Override
697  public ImmutableSet<R> rowKeySet() {
698    return rowKeyToIndex.keySet();
699  }
700
701  @NullableDecl private transient RowMap rowMap;
702
703  @Override
704  public Map<R, Map<C, V>> rowMap() {
705    RowMap map = rowMap;
706    return (map == null) ? rowMap = new RowMap() : map;
707  }
708
709  @WeakOuter
710  private class RowMap extends ArrayMap<R, Map<C, V>> {
711    private RowMap() {
712      super(rowKeyToIndex);
713    }
714
715    @Override
716    String getKeyRole() {
717      return "Row";
718    }
719
720    @Override
721    Map<C, V> getValue(int index) {
722      return new Row(index);
723    }
724
725    @Override
726    Map<C, V> setValue(int index, Map<C, V> newValue) {
727      throw new UnsupportedOperationException();
728    }
729
730    @Override
731    public Map<C, V> put(R key, Map<C, V> value) {
732      throw new UnsupportedOperationException();
733    }
734  }
735
736  /**
737   * Returns an unmodifiable collection of all values, which may contain duplicates. Changes to the
738   * table will update the returned collection.
739   *
740   * <p>The returned collection's iterator traverses the values of the first row key, the values of
741   * the second row key, and so on.
742   *
743   * @return collection of values
744   */
745  @Override
746  public Collection<V> values() {
747    return super.values();
748  }
749
750  @Override
751  Iterator<V> valuesIterator() {
752    return new AbstractIndexedListIterator<V>(size()) {
753      @Override
754      protected V get(int index) {
755        return getValue(index);
756      }
757    };
758  }
759
760  private static final long serialVersionUID = 0;
761}