com.google.common.collect.TreeBasedTable Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* Copyright (C) 2008 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.collect;
import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.base.Preconditions.checkNotNull;
import static java.util.Objects.requireNonNull;
import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Supplier;
import java.io.Serializable;
import java.util.Comparator;
import java.util.Iterator;
import java.util.Map;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.SortedMap;
import java.util.SortedSet;
import java.util.TreeMap;
import javax.annotation.CheckForNull;
/**
* Implementation of {@code Table} whose row keys and column keys are ordered by their natural
* ordering or by supplied comparators. When constructing a {@code TreeBasedTable}, you may provide
* comparators for the row keys and the column keys, or you may use natural ordering for both.
*
* The {@link #rowKeySet} method returns a {@link SortedSet} and the {@link #rowMap} method
* returns a {@link SortedMap}, instead of the {@link Set} and {@link Map} specified by the {@link
* Table} interface.
*
*
The views returned by {@link #column}, {@link #columnKeySet()}, and {@link #columnMap()} have
* iterators that don't support {@code remove()}. Otherwise, all optional operations are supported.
* Null row keys, columns keys, and values are not supported.
*
*
Lookups by row key are often faster than lookups by column key, because the data is stored in
* a {@code Map>}. A method call like {@code column(columnKey).get(rowKey)} still runs
* quickly, since the row key is provided. However, {@code column(columnKey).size()} takes longer,
* since an iteration across all row keys occurs.
*
* Because a {@code TreeBasedTable} has unique sorted values for a given row, both {@code
* row(rowKey)} and {@code rowMap().get(rowKey)} are {@link SortedMap} instances, instead of the
* {@link Map} specified in the {@link Table} interface.
*
*
Note that this implementation is not synchronized. If multiple threads access this table
* concurrently and one of the threads modifies the table, it must be synchronized externally.
*
*
See the Guava User Guide article on {@code Table}.
*
* @author Jared Levy
* @author Louis Wasserman
* @since 7.0
*/
@GwtCompatible(serializable = true)
@ElementTypesAreNonnullByDefault
public class TreeBasedTable extends StandardRowSortedTable {
private final Comparator columnComparator;
private static class Factory implements Supplier>, Serializable {
final Comparator comparator;
Factory(Comparator comparator) {
this.comparator = comparator;
}
@Override
public Map get() {
return new TreeMap<>(comparator);
}
private static final long serialVersionUID = 0;
}
/**
* Creates an empty {@code TreeBasedTable} that uses the natural orderings of both row and column
* keys.
*
* The method signature specifies {@code R extends Comparable} with a raw {@link Comparable},
* instead of {@code R extends Comparable}, and the same for {@code C}. That's
* necessary to support classes defined without generics.
*/
@SuppressWarnings("rawtypes") // https://github.com/google/guava/issues/989
public static TreeBasedTable create() {
return new TreeBasedTable<>(Ordering.natural(), Ordering.natural());
}
/**
* Creates an empty {@code TreeBasedTable} that is ordered by the specified comparators.
*
* @param rowComparator the comparator that orders the row keys
* @param columnComparator the comparator that orders the column keys
*/
public static TreeBasedTable create(
Comparator rowComparator, Comparator columnComparator) {
checkNotNull(rowComparator);
checkNotNull(columnComparator);
return new TreeBasedTable<>(rowComparator, columnComparator);
}
/**
* Creates a {@code TreeBasedTable} with the same mappings and sort order as the specified {@code
* TreeBasedTable}.
*/
public static TreeBasedTable create(TreeBasedTable table) {
TreeBasedTable result =
new TreeBasedTable<>(table.rowComparator(), table.columnComparator());
result.putAll(table);
return result;
}
TreeBasedTable(Comparator rowComparator, Comparator columnComparator) {
super(new TreeMap>(rowComparator), new Factory(columnComparator));
this.columnComparator = columnComparator;
}
// TODO(jlevy): Move to StandardRowSortedTable?
/**
* Returns the comparator that orders the rows. With natural ordering, {@link Ordering#natural()}
* is returned.
*
* @deprecated Use {@code table.rowKeySet().comparator()} instead.
*/
@Deprecated
public Comparator rowComparator() {
/*
* requireNonNull is safe because the factories require non-null Comparators, which they pass on
* to the backing collections.
*/
return requireNonNull(rowKeySet().comparator());
}
/**
* Returns the comparator that orders the columns. With natural ordering, {@link
* Ordering#natural()} is returned.
*
* @deprecated Store the {@link Comparator} alongside the {@link Table}. Or, if you know that the
* {@link Table} contains at least one value, you can retrieve the {@link Comparator} with:
* {@code ((SortedMap) table.rowMap().values().iterator().next()).comparator();}.
*/
@Deprecated
public Comparator columnComparator() {
return columnComparator;
}
// TODO(lowasser): make column return a SortedMap
/**
* {@inheritDoc}
*
* Because a {@code TreeBasedTable} has unique sorted values for a given row, this method
* returns a {@link SortedMap}, instead of the {@link Map} specified in the {@link Table}
* interface.
*
* @since 10.0 (mostly
* source-compatible since 7.0)
*/
@Override
public SortedMap row(R rowKey) {
return new TreeRow(rowKey);
}
private class TreeRow extends Row implements SortedMap {
@CheckForNull final C lowerBound;
@CheckForNull final C upperBound;
TreeRow(R rowKey) {
this(rowKey, null, null);
}
TreeRow(R rowKey, @CheckForNull C lowerBound, @CheckForNull C upperBound) {
super(rowKey);
this.lowerBound = lowerBound;
this.upperBound = upperBound;
checkArgument(
lowerBound == null || upperBound == null || compare(lowerBound, upperBound) <= 0);
}
@Override
public SortedSet keySet() {
return new Maps.SortedKeySet<>(this);
}
@Override
public Comparator comparator() {
return columnComparator();
}
int compare(Object a, Object b) {
// pretend we can compare anything
@SuppressWarnings("unchecked")
Comparator