Provides === and !== operators that return Boolean, delegate the equality determination to an Equality type class, and require the types of the two values compared to be in a subtype/supertype relationship.

By default under TripleEquals, any use of === will compile, just like the == operator:

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

scala> import TripleEquals._
import TripleEquals._

scala> 1L === 1 // A Long can equal an Int
res0: Boolean = true

scala> List(1, 2, 3) === Vector(1, 2, 3) // A List can equal a Vector
res1: Boolean = true

scala> "hi" === 1 // Likely a bug, because a String can never equal an Int
res2: Boolean = false

With SuperSafe Community Edition installed, the first two expressions above will be allowed to compile, but the third (which represents a likely bug) will not:

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

scala> import TripleEquals._
import TripleEquals._

scala> 1L === 1
res0: Boolean = true

scala> List(1, 2, 3) === Vector(1, 2, 3)
res1: Boolean = true

scala> "hi" === 1 // SuperSafe catches the bug at compile time
<console>:17: error: [Artima SuperSafe] Values of type String and Int may not be compared with
the === operator. If you really want to compare them for equality, configure Artima SuperSafe to allow
those types to be compared for equality.  For more information on this kind of error, see:
http://www.artima.com/supersafe_user_guide.html#safer-equality
       "hi" === 1
            ^

By contrast, TypeCheckedTripleEquals will prevent any of the above three expressions from compiling:

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

scala> import TypeCheckedTripleEquals._
import TypeCheckedTripleEquals._

scala> 1L === 1
<console>:17: error: types Long and Int do not adhere to the type constraint selected for
    the === and !== operators; the missing implicit parameter is of type org.scalactic.CanEqual[Long,Int]
       1L === 1
          ^

scala> List(1, 2, 3) === Vector(1, 2, 3)
<console>:17: error: types List[Int] and scala.collection.immutable.Vector[Int] do not adhere
    to the type constraint selected for the === and !== operators; the missing implicit parameter is
    of type org.scalactic.CanEqual[List[Int],scala.collection.immutable.Vector[Int]]
       List(1, 2, 3) === Vector(1, 2, 3)
                     ^

scala> "hi" === 1
<console>:17: error: types String and Int do not adhere to the type constraint selected for
    the === and !== operators; the missing implicit parameter is of type org.scalactic.CanEqual[String,Int]
       "hi" === 1
            ^

Trait TypeCheckedTripleEquals rejects comparisons of types Int and Long, List[Int] and Vector[Int], and String and Int, because none have a direct subtype/supertype relationship. To compare two types that are unrelated by inheritance under TypeCheckedTripleEquals, you could convert one of them to the other type (because a type is both a subtype and supertype of itself). Here's an example:

scala> 1L === 1.toLong // Now both sides are Long
res0: Boolean = true

scala> List(1, 2, 3) === Vector(1, 2, 3).toList // Now both sides are List[Int]
res1: Boolean = true

Nevertheless, a better (and the recommended) way to deal with this situation is to use a widening type ascription. A type ascription is simply a colon and a type placed next to a variable, usually surrounded by parentheses. For example, because AnyVal is a common supertype of Int and Long, you could solve the type error by widening the type of one side or the other to AnyVal. Because AnyVal is a supertype of both Int and Long, the type constraint will be satisfied:

scala> 1 === (1L: AnyVal)
res2: Boolean = true

scala> (1: AnyVal) === 1L
res3: Boolean = true

Similarly, since Seq[Int] is a common supertype of both Vector[Int] and List[Int], the type constraint can be satisfied by widening either to their common supertype, Seq[Int]:

scala> List(1, 2, 3) === (Vector(1, 2, 3): Seq[Int])
res4: Boolean = true

scala> (List(1, 2, 3): Seq[Int]) === Vector(1, 2, 3)
res5: Boolean = true

The primary intended use case for TypeCheckedTripleEquals is to enable tests to be very strict about which types can compared for equality, but it can also be used with production code where this level of strictness is desired.

Forcing implicit conversions before equality checks

You can also use a type ascription to force an implicit conversion before a value participates in an equality comparison. For example, although JavaConversions provides an implicit conversion between java.util.Set and scala.collection.mutable.Set, under TypeCheckedTripleEquals an equality comparison between those two types will not be allowed:

scala> import collection.JavaConversions._
import collection.JavaConversions._

scala> import collection.mutable
import collection.mutable

scala> import TypeCheckedTripleEquals._
import TypeCheckedTripleEquals._

scala> mutable.Set.empty[String] === new java.util.HashSet[String]
<console>:36: error: types scala.collection.mutable.Set[String] and java.util.HashSet[String] do not
    adhere to the type constraint selected for the === and !== operators; the missing implicit parameter
    is of type org.scalactic.CanEqual[scala.collection.mutable.Set[String],java.util.HashSet[String]]
       mutable.Set.empty[String] === new java.util.HashSet[String]
                                 ^

To force an implicit conversion of the Java HashSet to a Scala mutable.Set, after which the type constraint will be satisfied, you can use a type ascription:

scala> mutable.Set.empty[String] === (new java.util.HashSet[String]: mutable.Set[String])
res0: Boolean = true

Scoping equality policies

This trait will override or hide implicit methods defined by TripleEquals and can therefore be used to temporarily turn on or off type checking in a limited scope. Here's an example, in which TypeCheckedTripleEquals will cause a compiler error:

import org.scalactic._
import TypeCheckedTripleEquals._

object Example {

  def cmp(a: Int, b: Long): Int = {
    if (a === b) 0       // This line won't compile
    else if (a < b) -1
    else 1
  }

 def cmp(s: String, t: String): Int = {
   if (s === t) 0
   else if (s < t) -1
   else 1
 }
}

Because Int and Long are not in a subtype/supertype relationship, comparing 1 and 1L in the context of TypeCheckedTripleEquals will generate a compiler error:

Example.scala:9: error: types Int and Long do not adhere to the type constraint selected
  for the === and !== operators; the missing implicit parameter is of
  type org.scalactic.CanEqual[Int,Long]
        if (a === b) 0       // This line won't compile
              ^
one error found

You can “relax” the type checking locally by importing the members of TripleEquals in a limited scope:

package org.scalactic.examples.conversioncheckedtripleequals

import org.scalactic._
import TypeCheckedTripleEquals._

object Example {

  def cmp(a: Int, b: Long): Int = {
    import TripleEquals._
    if (a === b) 0
    else if (a < b) -1
    else 1
  }

 def cmp(s: String, t: String): Int = {
   if (s === t) 0
   else if (s < t) -1
   else 1
 }
}

With the above change, the Example.scala file compiles fine. The strict checking is disabled only inside the first cmp method that takes an Int and a Long. TypeCheckedTripleEquals is still enforcing its type constraint, for example, for the s === t expression in the other overloaded cmp method that takes strings.

Because the methods TripleEquals and TypeCheckedTripleEquals override all the methods defined in supertype TripleEqualsSupport, you can achieve the same kind of nested tuning of equality constraints whether you mix in traits, import from companion objects, or use some combination of both.

In short, you should be able to select a primary constraint level via either a mixin or import, then change that in nested scopes however you want, again either through a mixin or import, without getting any implicit conversion ambiguity. The innermost constraint level in scope will always be in force.