Next steps in Fuzzy Truth.

1. Add UsingCorrespondence.doesNotContain for iterables and doesNotContainEntry for maps and multimaps.

2. Improve the grammatical correctness of failure messages.
BEFORE: Correspondence.toString() was expected to be written for a plural subject (e.g. "are finite numbers within 0.00001 of") and this played badly with situations where the subject is singular — in particular, in maps where by definition there's only one value per key, and in particularly particular there was one failure message which would have read "but the value is <2.71828> which does not are finite numbers within 0.00001 <3.14159>". (I hadn't noticed this until now because it didn't show up in the example used in the tests.)
AFTER: Correspondence.toString() was expected to be written for a singular subject (e.g. "is a finite number within 0.00001 of"). After spending ages playing with these things, I've concluded that it's easier to phrase the statements so that they always refer to a singular subject (if we have a collection we can refer to "each element") than that they always refer to a plural subject. (I don't really want to have two methods on Correspondence, one for each case, and require implementers to have to think about this grammar stuff.)

3. Minor: Make the failure messages in the tests easier to understand by putting a + sign in front of each string-which-parses-as-an-integer, so that we can tell the difference between the string "+456" and the integer 456. (Although StringSubject quotes strings for display, IterableSubject et al do not. Perhaps they should: that's a separate question...)

4. Very minor: Fix up some more which/that errors. I know this isn't really the end of the world, but once I'd started picking at it I kinda wanted to be consistent.

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

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

@@ -45,7 +45,7 @@
 public abstract class Correspondence<A, E> {
 
   /**
-   * Returns a {@link Correspondence} between {@link Number} instances which considers instances to
+   * Returns a {@link Correspondence} between {@link Number} instances that considers instances to
    * correspond (i.e. {@link Correspondence#compare(Number, Number)} returns {@code true}) if the
    * double values of each instance (i.e. the result of calling {@link Number#doubleValue()} on
    * them) are finite values within {@code tolerance} of each other.
@@ -83,7 +83,7 @@ public boolean compare(Number actual, Number expected) {
 
     @Override
     public String toString() {
-      return "are finite numbers within " + tolerance + " of";
+      return "is a finite number within " + tolerance + " of";
     }
   }
 
@@ -95,12 +95,18 @@ public String toString() {
 
   /**
    * Returns a description of the correspondence, suitable to fill the gap in a failure message of
-   * the form {@code "Not true that <[a1, a2, a3]> contains exactly elements which ... <expected>"}.
+   * the form {@code "<some actual element> is an element that ... <some expected element>"}. Note
+   * that this is a fragment of a verb phrase which takes a singular subject.
    *
-   * <p>For example, for a {@code Correspondence<String, Integer>} which tests whether the actual
-   * string parses to the expected integer, this would return {@code "parse to"} to result in a
-   * failure message of the form {@code "Not true that <[foo, 123, bar]> contains exactly elements
-   * which parse to <[123, 456]>"}.
+   * <p>Example 1: For a {@code Correspondence<String, Integer>} that tests whether the actual
+   * string parses to the expected integer, this would return {@code "parses to"} to result in a
+   * failure message of the form {@code "<some actual string> is an element that parses to <some
+   * expected integer>"}.
+   *
+   * <p>Example 2: For the {@code Correspondence<Number, Number>} returns by {@link #tolerance} this
+   * returns {@code "is a finite number within " + tolerance + " of"} to result in a failure message
+   * of the form {@code "<some actual number> is an element that is a finite number within 0.0001 of
+   * <some expected number>"}.
    */
   @Override
   public abstract String toString();

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

@@ -522,7 +522,7 @@ private void pairwiseCheck(PairwiseChecker checker) {
    * expected} is an {@code E}.
    *
    * <p>Any of the methods on the returned object may throw {@link ClassCastException} if they
-   * encounter an actual element which is not of type {@code A}.
+   * encounter an actual element that is not of type {@code A}.
    */
   public <A, E> UsingCorrespondence<A, E> comparingElementsUsing(
       Correspondence<A, E> correspondence) {
@@ -550,28 +550,38 @@ private UsingCorrespondence(Correspondence<A, E> correspondence) {
     }
 
     /**
-     * Attests that the subject contains at least one element which corresponds to the given
-     * expected element.
+     * Attests that the subject contains at least one element that corresponds to the given expected
+     * element.
      */
     public void contains(@Nullable E expected) {
       for (A actual : getCastSubject()) {
         if (correspondence.compare(actual, expected)) {
           return;
         }
       }
-      fail("contains one or more elements that " + correspondence, expected);
+      fail("contains at least one element that " + correspondence, expected);
     }
 
     /** Attests that none of the actual elements correspond to the given element. */
-    @SuppressWarnings("unused") // TODO(b/29966314): Implement this and make it public.
-    private void doesNotContain(@Nullable E element) {
-      throw new UnsupportedOperationException();
+    public void doesNotContain(@Nullable E excluded) {
+      List<A> matchingElements = new ArrayList<A>();
+      for (A actual : getCastSubject()) {
+        if (correspondence.compare(actual, excluded)) {
+          matchingElements.add(actual);
+        }
+      }
+      if (!matchingElements.isEmpty()) {
+        failWithRawMessage(
+            "%s should not have contained an element that %s <%s>. "
+                + "It contained the following such elements: <%s>",
+            getDisplaySubject(), correspondence, excluded, matchingElements);
+      }
     }
 
     /**
-     * Attests that subject contains exactly elements which correspond to the expected elements,
-     * i.e. that there is a 1:1 mapping between the actual elements and the expected elements where
-     * each pair of elements correspond.
+     * Attests that subject contains exactly elements that correspond to the expected elements, i.e.
+     * that there is a 1:1 mapping between the actual elements and the expected elements where each
+     * pair of elements correspond.
      *
      * <p>To also test that the contents appear in the given order, make a call to {@code inOrder()}
      * on the object returned by this method.
@@ -583,9 +593,9 @@ private Ordered containsExactly(@Nullable E... expected) {
     }
 
     /**
-     * Attests that subject contains exactly elements which correspond to the expected elements,
-     * i.e. that there is a 1:1 mapping between the actual elements and the expected elements where
-     * each pair of elements correspond.
+     * Attests that subject contains exactly elements that correspond to the expected elements, i.e.
+     * that there is a 1:1 mapping between the actual elements and the expected elements where each
+     * pair of elements correspond.
      *
      * <p>To also test that the contents appear in the given order, make a call to {@code inOrder()}
      * on the object returned by this method.
@@ -597,7 +607,7 @@ private Ordered containsExactlyElementsIn(Iterable<E> expected) {
     }
 
     /**
-     * Attests that the subject contains elements which corresponds to all of the expected elements,
+     * Attests that the subject contains elements that corresponds to all of the expected elements,
      * i.e. that there is a 1:1 mapping between any subset of the actual elements and the expected
      * elements where each pair of elements correspond.
      *
@@ -612,7 +622,7 @@ private Ordered containsAllOf(@Nullable E first, @Nullable E second, @Nullable E
     }
 
     /**
-     * Attests that the subject contains elements which corresponds to all of the expected elements,
+     * Attests that the subject contains elements that corresponds to all of the expected elements,
      * i.e. that there is a 1:1 mapping between any subset of the actual elements and the expected
      * elements where each pair of elements correspond.
      *
@@ -627,7 +637,7 @@ private Ordered containsAllIn(Iterable<E> expected) {
     }
 
     /**
-     * Attests that the subject contains at least one element which corresponds to at least one of
+     * Attests that the subject contains at least one element that corresponds to at least one of
      * the expected elements.
      */
     @SuppressWarnings("unused") // TODO(b/29966314): Implement this and make it public.
@@ -636,7 +646,7 @@ private void containsAnyOf(@Nullable E first, @Nullable E second, @Nullable E...
     }
 
     /**
-     * Attests that the subject contains at least one element which corresponds to at least one of
+     * Attests that the subject contains at least one element that corresponds to at least one of
      * the expected elements.
      */
     @SuppressWarnings("unused") // TODO(b/29966314): Implement this and make it public.
@@ -645,7 +655,7 @@ private void containsAnyIn(Iterable<E> expected) {
     }
 
     /**
-     * Attests that the subject contains no elements which correspond to any of the given elements.
+     * Attests that the subject contains no elements that correspond to any of the given elements.
      * (Duplicates are irrelevant to this test, which fails if any of the subject elements
      * correspond to any of the given elements.)
      */
@@ -655,7 +665,7 @@ private void containsNoneOf(@Nullable E first, @Nullable E second, @Nullable E..
     }
 
     /**
-     * Attests that the subject contains no elements which correspond to any of the given elements.
+     * Attests that the subject contains no elements that correspond to any of the given elements.
      * (Duplicates are irrelevant to this test, which fails if any of the subject elements
      * correspond to any of the given elements.)
      */

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

@@ -199,7 +199,7 @@ public Ordered containsExactlyEntriesIn(Map<?, ?> expectedMap) {
    * <p>Note that keys will always be compared with regular object equality ({@link Object#equals}).
    *
    * <p>Any of the methods on the returned object may throw {@link ClassCastException} if they
-   * encounter an actual value which is not of type {@code A} or an expected value which is not of
+   * encounter an actual value that is not of type {@code A} or an expected value that is not of
    * type {@code E}.
    */
   public <A, E> UsingCorrespondence<A, E> comparingValuesUsing(
@@ -223,8 +223,8 @@ private UsingCorrespondence(Correspondence<A, E> correspondence) {
     }
 
     /**
-     * Fails if the map does not contain an entry with the given key and a value which corresponds
-     * to the given value.
+     * Fails if the map does not contain an entry with the given key and a value that corresponds to
+     * the given value.
      */
     public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValue) {
       if (getSubject().containsKey(expectedKey)) {
@@ -236,9 +236,9 @@ public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValu
         }
         // Found matching key with non-matching value.
         failWithRawMessage(
-            "Not true that %s contains the expected entry: it contains the key <%s>, but the value "
-                + "is <%s> which does not %s <%s>",
-            getDisplaySubject(), expectedKey, actualValue, correspondence, expectedValue);
+            "Not true that %s contains an entry with key <%s> and a value that %s <%s>. "
+                + "However, it has a mapping from that key to <%s>",
+            getDisplaySubject(), expectedKey, correspondence, expectedValue, actualValue);
       } else {
         // Did not find matching key.
         Set<Object> keys = new LinkedHashSet<Object>();
@@ -250,26 +250,32 @@ public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValu
         if (!keys.isEmpty()) {
           // Found matching values with non-matching keys.
           failWithRawMessage(
-              "Not true that %s contains the expected entry: it does not contain the key <%s>, "
-                  + "but does contain values which %s <%s> at the following keys: <%s>",
+              "Not true that %s contains an entry with key <%s> and a value that %s <%s>. "
+                  + "However, the following keys are mapped to such values: <%s>",
               getDisplaySubject(), expectedKey, correspondence, expectedValue, keys);
         } else {
           // Did not find matching key or value.
           failWithRawMessage(
-              "Not true that %s contains the expected entry: it does not contain the key <%s>, "
-                  + "and it does not contain any values which %s <%s>",
+              "Not true that %s contains an entry with key <%s> and a value that %s <%s>",
               getDisplaySubject(), expectedKey, correspondence, expectedValue);
         }
       }
     }
 
     /**
-     * Fails if the map contains an entry with the given key and a value which corresponds to the
+     * Fails if the map contains an entry with the given key and a value that corresponds to the
      * given value.
      */
-    @SuppressWarnings("unused") // TODO(b/29966314): Implement this and make it public.
-    private void doesNotContainEntry(@Nullable Object key, @Nullable E value) {
-      throw new UnsupportedOperationException();
+    public void doesNotContainEntry(@Nullable Object excludedKey, @Nullable E excludedValue) {
+      if (getSubject().containsKey(excludedKey)) {
+        A actualValue = getCastSubject().get(excludedKey);
+        if (correspondence.compare(actualValue, excludedValue)) {
+          failWithRawMessage(
+              "Not true that %s does not contain an entry with key <%s> and a value that %s <%s>. "
+                  + "It maps that key to <%s>",
+              getDisplaySubject(), excludedKey, correspondence, excludedValue, actualValue);
+        }
+      }
     }
 
     /** Fails if the map is not empty. */
@@ -280,7 +286,7 @@ private Ordered containsExactly() {
     }
 
     /**
-     * Fails if the map does not contain exactly the given set of keys mapping to values which
+     * Fails if the map does not contain exactly the given set of keys mapping to values that
      * correspond to the given values.
      *
      * <p>The values must all be of type {@code E}, and a {@link ClassCastException} will be thrown
@@ -297,7 +303,7 @@ private Ordered containsExactly(@Nullable Object k0, @Nullable E v0, Object... r
     }
 
     /**
-     * Fails if the map does not contain exactly the keys in the given map, mapping to values which
+     * Fails if the map does not contain exactly the keys in the given map, mapping to values that
      * correspond to the values of the given map.
      */
     @CanIgnoreReturnValue

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

@@ -341,7 +341,7 @@ private static <K, V> String countDuplicatesMultimap(Multimap<K, V> multimap) {
    * <p>Note that keys will always be compared with regular object equality ({@link Object#equals}).
    *
    * <p>Any of the methods on the returned object may throw {@link ClassCastException} if they
-   * encounter an actual value which is not of type {@code A}.
+   * encounter an actual value that is not of type {@code A}.
    */
   public <A, E> UsingCorrespondence<A, E> comparingValuesUsing(
       Correspondence<A, E> correspondence) {
@@ -365,7 +365,7 @@ private UsingCorrespondence(Correspondence<A, E> correspondence) {
     }
 
     /**
-     * Fails if the multimap does not contain an entry with the given key and a value which
+     * Fails if the multimap does not contain an entry with the given key and a value that
      * corresponds to the given value.
      */
     public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValue) {
@@ -380,9 +380,9 @@ public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValu
         }
         // Found matching key with non-matching values.
         failWithRawMessage(
-            "Not true that %s contains the expected entry: it contains the key <%s>, but the "
-                + "values are <%s> none of which %s <%s>",
-            getDisplaySubject(), expectedKey, actualValues, correspondence, expectedValue);
+            "Not true that %s contains at least one entry with key <%s> and a value that %s <%s>. "
+                + "However, it has a mapping from that key to <%s>",
+            getDisplaySubject(), expectedKey, correspondence, expectedValue, actualValues);
       } else {
         // Did not find matching key.
         Set<Object> keys = new LinkedHashSet<Object>();
@@ -394,31 +394,43 @@ public void containsEntry(@Nullable Object expectedKey, @Nullable E expectedValu
         if (!keys.isEmpty()) {
           // Found matching values with non-matching keys.
           failWithRawMessage(
-              "Not true that %s contains the expected entry: it does not contain the key <%s>, "
-                  + "but does contain values which %s <%s> at the following keys: <%s>",
+              "Not true that %s contains at least one entry with key <%s> and a value that %s <%s>."
+                  + " However, the following keys are mapped to such values: <%s>",
               getDisplaySubject(), expectedKey, correspondence, expectedValue, keys);
         } else {
           // Did not find matching key or value.
           failWithRawMessage(
-              "Not true that %s contains the expected entry: it does not contain the key <%s>, "
-                  + "and it does not contain any values which %s <%s>",
+              "Not true that %s contains at least one entry with key <%s> and a value that %s <%s>",
               getDisplaySubject(), expectedKey, correspondence, expectedValue);
         }
       }
     }
 
     /**
-     * Fails if the multimap contains an entry with the given key and a value which corresponds to
+     * Fails if the multimap contains an entry with the given key and a value that corresponds to
      * the given value.
      */
-    @SuppressWarnings("unused") // TODO(b/29966314): Implement this and make it public.
-    private void doesNotContainEntry(@Nullable Object key, @Nullable E value) {
-      throw new UnsupportedOperationException();
+    public void doesNotContainEntry(@Nullable Object excludedKey, @Nullable E excludedValue) {
+      if (getSubject().containsKey(excludedKey)) {
+        Collection<A> actualValues = getCastSubject().asMap().get(excludedKey);
+        List<A> matchingValues = new ArrayList<A>();
+        for (A actualValue : actualValues) {
+          if (correspondence.compare(actualValue, excludedValue)) {
+            matchingValues.add(actualValue);
+          }
+        }
+        if (!matchingValues.isEmpty()) {
+          failWithRawMessage(
+              "Not true that %s did not contain an entry with key <%s> and a value that %s <%s>. "
+                  + "It maps that key to the following such values: <%s>",
+              getDisplaySubject(), excludedKey, correspondence, excludedValue, matchingValues);
+        }
+      }
     }
 
     /**
      * Fails if the map does not contain exactly the keys in the given multimap, mapping to values
-     * which correspond to the values of the given multimap.
+     * that correspond to the values of the given multimap.
      *
      * <p>A subsequent call to {@link Ordered#inOrder} may be made if the caller wishes to verify
      * that the two Multimaps iterate fully in the same order. That is, their key sets iterate in

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

@@ -44,7 +44,7 @@ public boolean compare(Object actual, Object expected) {
 
         @Override
         public String toString() {
-          return "example";
+          return "has example property";
         }
       };
 
@@ -143,8 +143,8 @@ public void testTolerance_viaIterableSubjectContains_failure() {
     } catch (AssertionError expected) {
       assertThat(expected)
           .hasMessage(
-              "Not true that <[1.02, 2.04, 3.08]> contains one or more elements that "
-                  + "are finite numbers within 0.05 of <3.0>");
+              "Not true that <[1.02, 2.04, 3.08]> contains at least one element that "
+                  + "is a finite number within 0.05 of <3.0>");
     }
   }
 }