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).

Instances of this are typically used via IterableSubject.comparingElementsUsing(com.google.common.truth.Correspondence<A, E>). (TODO(b/29966314): Mention MapSubject and MultimapSubject methods when they're added.)

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).
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. Correspondence#compare(Number, Number) 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 Correspondence#compare(Number, Number) 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(@Nullable
                                A actual,
                                @Nullable
                                E expected)

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

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(@Nullable
                                        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