com.google.common.truth

Class Correspondence<A,E>

java.lang.Object

com.google.common.truth.Correspondence<A,E>

public abstract class Correspondence<A,E>
extends Object

Determines whether an instance of type A corresponds in some way to an instance of type E. For example, the implementation returned by the tolerance(double) factory method implements approximate equality between numeric values, with values being said to correspond if the difference between them is does not exceed some fixed tolerance. The instances of type A are typically actual values from a collection returned by the code under test; the instances of type E are typically expected values with which the actual values are compared by the test.

The correspondence is required to be consistent: for any given values actual and expected, multiple invocations of compare(actual, expected) must consistently return true or consistently return false (provided that neither value is modified). Although A and E will often be the same types, they are not required to be the same, and even if they are it is not required that the correspondence should have any of the other properties of an equivalence relation (reflexivity, symmetry, or transitivity).

Subclasses may optionally override formatDiff(A, E). This results in failure messages including formatted diffs between expected and actual elements, where possible.

Instances of this are typically used via IterableSubject.comparingElementsUsing(com.google.common.truth.Correspondence<A, E>), MapSubject.comparingValuesUsing(com.google.common.truth.Correspondence<A, E>), or MultimapSubject.comparingValuesUsing(com.google.common.truth.Correspondence<A, E>).

Author:

Pete Gillin

Constructor Summary

Constructors

Constructor and Description
Correspondence()

Method Summary

Modifier and Type	Method and Description
abstract boolean	compare(A actual, E expected) Returns whether or not the actual value is said to correspond to the expected value for the purposes of this test.
boolean	equals(Object o) Deprecated. Object.equals(Object) is not supported. If you meant to compare objects using this Correspondence, use compare(A, E).
String	formatDiff(A actual, E expected) Returns a String describing the difference between the actual and expected values, if possible, or null if not.
int	hashCode() Deprecated. Object.hashCode() is not supported.
static Correspondence<Number,Number>	tolerance(double tolerance) Returns a Correspondence between Number instances that considers instances to correspond (i.e.
abstract String	toString() Returns a description of the correspondence, suitable to fill the gap in a failure message of the form {@code " is an element that ...

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Correspondence

public Correspondence()

Method Detail

tolerance

public static Correspondence<Number,Number> tolerance(double tolerance)

Returns a Correspondence between Number instances that considers instances to correspond (i.e. compare(Object, Object) returns true) if the double values of each instance (i.e. the result of calling Number.doubleValue() on them) are finite values within tolerance of each other.

• It does not consider instances to correspond if either value is infinite or NaN.
• The conversion to double may result in a loss of precision for some numeric types.
• The compare(Object, Object) method throws a NullPointerException if either Number instance is null.

Parameters:

tolerance - an inclusive upper bound on the difference between the double values of the two Number instances, which must be a non-negative finite value, i.e. not Double.NaN, Double.POSITIVE_INFINITY, or negative, including -0.0

compare

public abstract boolean compare(@NullableDecl
                                A actual,
                                @NullableDecl
                                E expected)

Returns whether or not the actual value is said to correspond to the expected value for the purposes of this test.

formatDiff

@NullableDecl
public String formatDiff(@NullableDecl
                                       A actual,
                                       @NullableDecl
                                       E expected)

Returns a String describing the difference between the actual and expected values, if possible, or null if not.

The implementation on the Correspondence base class always returns null. To enable diffing, subclasses should override this method.

Assertions should only invoke this with parameters for which compare(A, E) returns false.

toString

public abstract String toString()

Returns a description of the correspondence, suitable to fill the gap in a failure message of the form "<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.

Example 1: For a Correspondence<String, Integer> that tests whether the actual string parses to the expected integer, this would return "parses to" to result in a failure message of the form "<some actual string> is an element that parses to <some expected integer>".

Example 2: For the Correspondence<Number, Number> returns by tolerance(double) this returns "is a finite number within " + tolerance + " of" to result in a failure message of the form "<some actual number> is an element that is a finite number within 0.0001 of <some expected number>".

Overrides:

toString in class Object

equals

@Deprecated
public final boolean equals(@NullableDecl
                                        Object o)

Deprecated. Object.equals(Object) is not supported. If you meant to compare objects using this Correspondence, use compare(A, E).

Overrides:

equals in class Object

Throws:

UnsupportedOperationException - always

hashCode

@Deprecated
public final int hashCode()

Deprecated. Object.hashCode() is not supported.

Overrides:

hashCode in class Object

Throws:

UnsupportedOperationException - always