Defines a custom way to determine equality for a type when compared with another value of the same type.

Equivalence enables you to define alternate notions of equality for types that can be used with ScalaUtil's TypeCheckedTripleEquals and ConversionCheckedTripleEquals traits. These traits can be used to perform equality comparisons with type constraints enforced at compile time using ScalaUtil's === and !== syntax and ScalaTest's should === syntax of Matchers trait.

Because Equality extends Equivalence, you automatically define an Equivalence[T] when you define an Equality[T]. Most often you will usually want to define custom Equalitys, because they will be more generally useful: they are also used by Scalactic's TripleEquals trait and ScalaTest's equal, be, and contain matcher syntax. However, if you really want just an Equivalence, and writing an Equality is inconvenient, you can write an Equivalence directly for a type.

For example, say you have a case class that includes a Double value:

scala> case class Person(name: String, age: Double)
defined class Person

Imagine you are calculating the age values in such as way that occasionally tests are failing because of rounding differences that you actually don't care about. For example, you expect an age of 29.0, but you're sometimes seeing 29.0001:

scala> import org.scalactic._
import org.scalactic._

scala> import TypeCheckedTripleEquals._
import TypeCheckedTripleEquals._

scala> Person("Joe", 29.0001) === Person("Joe", 29.0)
res0: Boolean = false

The === operator of TypeCheckedTripleEquals looks for an implicit Equivalence[SUPER], where SUPER is either the left-hand or right-hand type, whichever one is a supertype of the other. In this case, both sides are Person (which is considered a supertype of itself), so the compiler will look for an Equivalence[Person]. Because you didn't specifically provide an implicit Equivalence[Person], === will fall back on default equality, because an Equality[Person] is-an Equivalence[Person]. The default Equality[Person] will call Person's equals method. That equals method, provided by the Scala compiler because Person is a case class, will declare these two objects unequal because 29.001 does not exactly equal 29.0.

To make the equality check more forgiving, you could define an implicit Equivalence[Person] that compares the age Doubles with a tolerance, like this:

scala> import Tolerance._
import Tolerance._

scala> implicit val personEq =
     |   new Equivalence[Person] {
     |     def areEquivalent(a: Person, b: Person): Boolean =
     |       a.name == b.name && a.age === b.age +- 0.0002
     |   }
personEq: org.scalactic.Equivalence[Person] = $anon$1@7892bd8

Now the === operator will use your more forgiving Equivalence[Person] for the equality check instead of default equality:

scala> Person("Joe", 29.0001) === Person("Joe", 29.0)
res1: Boolean = true