Document that ComparisonChain is mostly obsolete.

If you are able to use the Java 8 API, you should almost certainly be using the `Comparator` methods introduced there. They are less error-prone and more succinct. In particular they avoid slip-ups like `compare(a.foo(), a.foo())` or `compare(a.foo(), b.bar())`.

RELNOTES=Documented that `ComparisonChain` is mostly obsolete.
PiperOrigin-RevId: 475862634

guava-tests/test/com/google/common/collect/ComparisonChainTest.java

@@ -16,11 +16,20 @@
 
 package com.google.common.collect;
 
+import static com.google.common.base.MoreObjects.toStringHelper;
 import static com.google.common.truth.Truth.assertThat;
+import static com.google.common.truth.Truth.assertWithMessage;
+import static java.lang.Integer.signum;
+import static java.util.Comparator.comparing;
+import static java.util.Comparator.naturalOrder;
+import static java.util.Comparator.nullsLast;
 
 import com.google.common.annotations.GwtCompatible;
+import com.google.common.primitives.Booleans;
+import java.util.Comparator;
 import junit.framework.AssertionFailedError;
 import junit.framework.TestCase;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * Unit test for {@link ComparisonChain}.
@@ -118,4 +127,95 @@ public void testCompareTrueFirst() {
  assertThat(ComparisonChain.start().compareTrueFirst(false, true).result()).isGreaterThan(0);
  assertThat(ComparisonChain.start().compareTrueFirst(false, false).result()).isEqualTo(0);
  }
+
+ enum TriState {
+ FALSE,
+ MAYBE,
+ TRUE,
+ }
+
+ static class Foo {
+ private final String aString;
+ private final int anInt;
+ private final @Nullable TriState anEnum;
+
+ Foo(String aString, int anInt, @Nullable TriState anEnum) {
+ this.aString = aString;
+ this.anInt = anInt;
+ this.anEnum = anEnum;
+ }
+
+ @Override
+ public String toString() {
+ return toStringHelper(this)
+ .add("aString", aString)
+ .add("anInt", anInt)
+ .add("anEnum", anEnum)
+ .toString();
+ }
+ }
+
+ /** Validates that the Comparator equivalent we document is correct. */
+ public void testComparatorEquivalent() {
+ Comparator<Foo> comparatorUsingComparisonChain =
+ (a, b) ->
+ ComparisonChain.start()
+ .compare(a.aString, b.aString)
+ .compare(a.anInt, b.anInt)
+ .compare(a.anEnum, b.anEnum, Ordering.natural().nullsLast())
+ .result();
+ Comparator<Foo> comparatorUsingComparatorMethods =
+ comparing((Foo foo) -> foo.aString)
+ .thenComparing(foo -> foo.anInt)
+ .thenComparing(foo -> foo.anEnum, nullsLast(naturalOrder()));
+ ImmutableList<Foo> instances =
+ ImmutableList.of(
+ new Foo("a", 1, TriState.TRUE),
+ new Foo("a", 2, TriState.TRUE),
+ new Foo("b", 1, TriState.FALSE),
+ new Foo("b", 1, TriState.TRUE),
+ new Foo("b", 1, null));
+ for (Foo a : instances) {
+ for (Foo b : instances) {
+ int comparedUsingComparisonChain = signum(comparatorUsingComparisonChain.compare(a, b));
+ int comparedUsingComparatorMethods = signum(comparatorUsingComparatorMethods.compare(a, b));
+ assertWithMessage("%s vs %s", a, b)
+ .that(comparedUsingComparatorMethods)
+ .isEqualTo(comparedUsingComparisonChain);
+ }
+ }
+ }
+
+ static class Bar {
+ private final boolean isBaz;
+
+ Bar(boolean isBaz) {
+ this.isBaz = isBaz;
+ }
+
+ boolean isBaz() {
+ return isBaz;
+ }
+ }
+
+ /**
+ * Validates that {@link Booleans#trueFirst()} and {@link Booleans#falseFirst()} can be used with
+ * {@link Comparator} when replacing {@link ComparisonChain#compareTrueFirst} and {@link
+ * ComparisonChain#compareFalseFirst}, as we document.
+ */
+ public void testTrueFirstFalseFirst() {
+ Bar trueBar = new Bar(true);
+ Bar falseBar = new Bar(false);
+
+ assertThat(ComparisonChain.start().compareTrueFirst(trueBar.isBaz(), falseBar.isBaz()).result())
+ .isLessThan(0);
+ Comparator<Bar> trueFirstComparator = comparing(Bar::isBaz, Booleans.trueFirst());
+ assertThat(trueFirstComparator.compare(trueBar, falseBar)).isLessThan(0);
+
+ assertThat(
+ ComparisonChain.start().compareFalseFirst(falseBar.isBaz(), trueBar.isBaz()).result())
+ .isLessThan(0);
+ Comparator<Bar> falseFirstComparator = comparing(Bar::isBaz, Booleans.falseFirst());
+ assertThat(falseFirstComparator.compare(falseBar, trueBar)).isLessThan(0);
+ }
 }

guava/src/com/google/common/collect/ComparisonChain.java

@@ -24,7 +24,10 @@
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * A utility for performing a chained comparison statement. For example:
+ * A utility for performing a chained comparison statement. <b>Note:</b> Java 8+ users should
+ * generally prefer the methods in {@link Comparator}; see <a href="#java8">below</a>.
+ *
+ * <p>Example usage of {@code ComparisonChain}:
  *
  * <pre>{@code
  * public int compareTo(Foo that) {
@@ -52,6 +55,37 @@
  * "https://github.com/google/guava/wiki/CommonObjectUtilitiesExplained#comparecompareto">{@code
  * ComparisonChain}</a>.
  *
+ * <h4 id="java8">Java 8+ equivalents</h4>
+ *
+ * If you are using Java version 8 or greater, you should generally use the static methods in {@link
+ * Comparator} instead of {@code ComparisonChain}. The example above can be implemented like this:
+ *
+ * <pre>{@code
+ * import static java.util.Comparator.comparing;
+ * import static java.util.Comparator.nullsLast;
+ * import static java.util.Comparator.naturalOrder;
+ *
+ * ...
+ * private static final Comparator<Foo> COMPARATOR =
+ * comparing((Foo foo) -> foo.aString)
+ * .thenComparing(foo -> foo.anInt)
+ * .thenComparing(foo -> foo.anEnum, nullsLast(naturalOrder()));}
+ *
+ * {@code @Override}{@code
+ * public int compareTo(Foo that) {
+ * return COMPARATOR.compare(this, that);
+ * }
+ * }</pre>
+ *
+ * <p>With method references it is more succinct: {@code comparing(Foo::aString)} for example.
+ *
+ * <p>Using {@link Comparator} avoids certain types of bugs, for example when you meant to write
+ * {@code .compare(a.foo, b.foo)} but you actually wrote {@code .compare(a.foo, a.foo)} or {@code
+ * .compare(a.foo, b.bar)}. {@code ComparisonChain} also has a potential performance problem that
+ * {@code Comparator} doesn't: it evaluates all the parameters of all the {@code .compare} calls,
+ * even when the result of the comparison is already known from previous {@code .compare} calls.
+ * That can be expensive.
+ *
  * @author Mark Davis
  * @author Kevin Bourrillion
  * @since 2.0
@@ -243,6 +277,12 @@ public final ComparisonChain compare(Boolean left, Boolean right) {
  * Compares two {@code boolean} values, considering {@code true} to be less than {@code false},
  * <i>if</i> the result of this comparison chain has not already been determined.
  *
+ * <p>Java 8+ users: you can get the equivalent from {@link Booleans#trueFirst()}. For example:
+ *
+ * <pre>
+ * Comparator.comparing(Foo::isBar, {@link Booleans#trueFirst()})
+ * </pre>
+ *
  * @since 12.0
  */
  public abstract ComparisonChain compareTrueFirst(boolean left, boolean right);
@@ -251,6 +291,12 @@ public final ComparisonChain compare(Boolean left, Boolean right) {
  * Compares two {@code boolean} values, considering {@code false} to be less than {@code true},
  * <i>if</i> the result of this comparison chain has not already been determined.
  *
+ * <p>Java 8+ users: you can get the equivalent from {@link Booleans#falseFirst()}. For example:
+ *
+ * <pre>
+ * Comparator.comparing(Foo::isBar, {@link Booleans#falseFirst()})
+ * </pre>
+ *
  * @since 12.0 (present as {@code compare} since 2.0)
  */
  public abstract ComparisonChain compareFalseFirst(boolean left, boolean right);