Add the one-function transforming factory method for Correspondence.

RELNOTES=You can now create a Correspondence instance that transforms the actual elements using a lambda or method reference and tests for equality with the expected elements, with the Correspondence.transforming factory method.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=233729880

Author: peteg

core/src/main/java/com/google/common/truth/Correspondence.java

@@ -15,6 +15,7 @@
  */
 package com.google.common.truth;
 
+import static com.google.common.base.Functions.identity;
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkState;
 import static com.google.common.truth.DoubleSubject.checkTolerance;
@@ -24,7 +25,9 @@
 import static com.google.common.truth.Platform.getStackTraceAsString;
 import static java.util.Arrays.asList;
 
+import com.google.common.base.Function;
 import com.google.common.base.Joiner;
+import com.google.common.base.Objects;
 import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableList;
 import java.util.Arrays;
@@ -56,6 +59,8 @@
  *
  * @author Pete Gillin
  */
+// TODO(b/119038898): Once there is little reason to prefer subclassing to factory methods, change
+// the class-level javadoc to point folks at the factory methods and drop references to subclassing.
 public abstract class Correspondence<A, E> {
 
   /**
@@ -146,6 +151,75 @@ public String toString() {
     }
   }
 
+  /**
+   * Constructs a {@link Correspondence} that compares elements by transforming the actual elements
+   * using the given function and tests for equality with the expected elements. If the transformed
+   * actual element (i.e. the output of the given function) is null, it will correspond to a null
+   * expected element.
+   *
+   * <p>The correspondence does not support formatting of diffs (see {@link #formatDiff}).
+   *
+   * <p>Note that, if you the data you are asserting about contains null actual values, your
+   * function may be invoked with a null argument. If this causes it to throw a {@link
+   * NullPointerException}, then your test will fail. (See {@link Correspondence#compare} for more
+   * detail on how exceptions are handled.) In particular, this applies if your predicate is an
+   * instance method reference on the actual value (as in the example below). If you want a null
+   * actual element to correspond to a null expected element, you must ensure that your function
+   * transforms a null input to a null output.
+   *
+   * <p>Example:
+   *
+   * <pre>{@code
+   * static final Correspondence<MyRecord, Integer> HAS_ID =
+   *     Correspondence.transforming(MyRecord::getId, "has an ID of");
+   * }</pre>
+   *
+   * This can be used as follows:
+   *
+   * <pre>{@code
+   * assertThat(myRecords).comparingElementsUsing(HAS_ID).containsExactly(123, 456, 789);
+   * }</pre>
+   *
+   * @param actualTransform a {@link Function} taking an actual value and returning a new value
+   *     which will be compared with an expected value to determine whether they correspond
+   * @param description should fill the gap in a failure message of the form {@code "not true that
+   *     <some actual element> is an element that <description> <some expected element>"}, e.g.
+   *     {@code "has an ID of"}
+   */
+  // TODO(b/119038898): Mention formattingDiffsUsing in the javadoc when it exists.
+  public static <A, E> Correspondence<A, E> transforming(
+      Function<A, ? extends E> actualTransform, String description) {
+    return new Transforming<>(actualTransform, identity(), description);
+  }
+
+  // TODO(b/119038894): Add the two-function overload of transforming that also transforms expected.
+
+  private static final class Transforming<A, E> extends Correspondence<A, E> {
+
+    private final Function<? super A, ?> actualTransform;
+    private final Function<? super E, ?> expectedTransform;
+    private final String description;
+
+    private Transforming(
+        Function<? super A, ?> actualTransform,
+        Function<? super E, ?> expectedTransform,
+        String description) {
+      this.actualTransform = actualTransform;
+      this.expectedTransform = expectedTransform;
+      this.description = description;
+    }
+
+    @Override
+    public boolean compare(@NullableDecl A actual, @NullableDecl E expected) {
+      return Objects.equal(actualTransform.apply(actual), expectedTransform.apply(expected));
+    }
+
+    @Override
+    public String toString() {
+      return description;
+    }
+  }
+
   /**
    * Returns a {@link Correspondence} between {@link Number} instances that considers instances to
    * correspond (i.e. {@link Correspondence#compare(Object, Object)} returns {@code true}) if the

core/src/test/java/com/google/common/truth/CorrespondenceTest.java

@@ -20,7 +20,9 @@
 import static java.util.Arrays.asList;
 import static org.junit.Assert.fail;
 
+import com.google.common.base.Function;
 import com.google.common.collect.ImmutableList;
+import org.checkerframework.checker.nullness.compatqual.NullableDecl;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
@@ -135,6 +137,97 @@ public void testFrom_viaIterableSubjectContainsExactly_null() {
         .startsWith("compare(null, foot) threw java.lang.NullPointerException");
   }
 
+  // Tests of the 'transform' factory methods.
+
+  private static final Correspondence<String, Integer> LENGTHS =
+      Correspondence.transforming(
+          new Function<String, Integer>() {
+            @Override
+            @NullableDecl
+            public Integer apply(String str) {
+              return str.length();
+            }
+          },
+          "has a length of");
+
+  private static final Correspondence<String, Integer> HYPHEN_INDEXES =
+      Correspondence.transforming(
+          new Function<String, Integer>() {
+            @Override
+            @NullableDecl
+            public Integer apply(String str) {
+              int index = str.indexOf('-');
+              return (index >= 0) ? index : null;
+            }
+          },
+          "has a hyphen at an index of");
+
+  @Test
+  public void testTransforming_actual_compare() {
+    assertThat(LENGTHS.compare("foo", 3)).isTrue();
+    assertThat(LENGTHS.compare("foot", 4)).isTrue();
+    assertThat(LENGTHS.compare("foo", 4)).isFalse();
+  }
+
+  @Test
+  public void testTransforming_actual_formatDiff() {
+    assertThat(LENGTHS.formatDiff("foo", 4)).isNull();
+  }
+
+  @Test
+  public void testTransforming_actual_toString() {
+    assertThat(LENGTHS.toString()).isEqualTo("has a length of");
+  }
+
+  @Test
+  public void testTransforming_actual_viaIterableSubjectContainsExactly_success() {
+    assertThat(ImmutableList.of("feet", "barns", "gallons"))
+        .comparingElementsUsing(LENGTHS)
+        .containsExactly(4, 5, 7)
+        .inOrder();
+  }
+
+  @Test
+  public void testTransforming_actual_viaIterableSubjectContainsExactly_failure() {
+    expectFailure
+        .whenTesting()
+        .that(ImmutableList.of("feet", "barns", "gallons"))
+        .comparingElementsUsing(LENGTHS)
+        .containsExactly(4, 5);
+    assertThat(expectFailure.getFailure())
+        .hasMessageThat()
+        .isEqualTo(
+            "Not true that <[feet, barns, gallons]> contains exactly one element that has a length "
+                + "of each element of <[4, 5]>. It has unexpected elements <[gallons]>");
+  }
+
+  @Test
+  public void testTransforming_actual_viaIterableSubjectContainsExactly_nullActual() {
+    expectFailure
+        .whenTesting()
+        .that(asList("feet", "barns", null))
+        .comparingElementsUsing(LENGTHS)
+        .containsExactly(4, 5);
+    assertFailureKeys(
+        "Not true that <[feet, barns, null]> contains exactly one element that has a length of "
+            + "each element of <[4, 5]>. It has unexpected elements <[null]>",
+        "additionally, one or more exceptions were thrown while comparing elements",
+        "first exception");
+    assertThatFailure()
+        .factValue("first exception")
+        .startsWith("compare(null, 4) threw java.lang.NullPointerException");
+  }
+
+  @Test
+  public void testTransforming_actual_viaIterableSubjectContainsExactly_nullTransformed() {
+    // "mailing-list" and "chat-room" have hyphens at index 7 and 4 respectively.
+    // "forum" contains no hyphen so the Function in HYPHEN_INDEXES transforms it to null.
+    assertThat(ImmutableList.of("mailing-list", "chat-room", "forum"))
+        .comparingElementsUsing(HYPHEN_INDEXES)
+        .containsExactly(7, 4, null)
+        .inOrder();
+  }
+
   // Tests of the 'tolerance' factory method. Includes both direct tests of the compare method and
   // indirect tests using it in a basic call chain.