All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • org.scalautils.TripleEqualsSupport.scala Maven / Gradle / Ivy

    The newest version!
    /*
 * Copyright 2001-2013 Artima, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.scalautils

import TripleEqualsSupport._

/**
 * Trait that defines abstract methods used to enforce compile-time type constraints for equality comparisons, and defines === and !== operators
 * used by matchers.
 *
 * 
    
 * The abstract methods of this trait are selectively implemented as implicit by subclasses to enable a spectrum of type constraints for the
 * === and !== operators. As an illustration, if in the expression, a === b, the type of a
 * is A and b is B, the following three levels of compile-time checking can be obtained from
 * TripleEqualsSupport subtraits:
 * 
    
 *
 * 
    
 * Unchecked - A and B can be any two types. This (weakest) constraint level is available from
 * subtraits TripleEquals and LegacyTripleEquals.
 * 
    
 * 
 * 
    
 * Conversion checked - A must be a subtype of B, or vice versa, or an implicit conversion must be available that converts
 * A to B, or vice versa. (Both A and B can be the same type, because a type is considered a subtype
 * of itself.)
 * This (intermediate) constraint level is available from subtraits ConversionCheckedTripleEquals and ConversionCheckedLegacyTripleEquals.
 * 
    
 * 
 * 
    
 * Type checked - A must be a subtype of B, or vice versa.
 * (Both A and B can be the same type, because a type is considered a subtype
 * of itself.)
 * This (strongest) constraint level is available from subtraits TypeCheckedTripleEquals and TypeCheckedLegacyTripleEquals.
 * 
    
 *
 * 
    
 * The difference between the regular and “legacy” variants of each pair of traits is that the  === and !== operators
 * provided by the regular variants result in Boolean, whereas those of the legacy variants result in Option[String]. For example, were you
 * to mix in TripleEquals, the expression 1 + 1 === 3 would return false. Were you to mix in LegacyTripleEquals,
 * by contrast, the expression 1 + 1 === 3 would return Some("2 did not equal 3").
 * 
    
 *
 * 
    
 * The purpose of the legacy variants is to maintain compatibility with
 * existing code that uses ScalaTest's original === defined in trait org.scalatest.Assertions. This
 * === operator returned an
 * Option[String] to facilitate better error messages. With the advent of macros in Scala 2.10, it is possible to obtain good error messages by making
 * assert a macro. Once ScalaTest no longer supports Scala 2.9, the legacy variants (LegacyTripleEquals,
 * ConversionCheckedLegacyTripleEquals, and TypeCheckedLegacyTripleEquals) will be deprecated and eventually removed, === will
 * return only Boolean, and good error
 * messages will be obtained via macros. 
 * 
    
 * 
 * 
    
 * This trait defines all methods that need to be defined implicitly by the six subtraits so that if multiple subtraits are used together, the inner-most
 * subtrait in scope can not only enable the implicits it needs by overriding or hiding those methods (currently-in-scope as regular, non-implicit methods) and making
 * them implicit, it can also disable any implicits enabled by its sibling subtraits in enclosing scopes. For example, if your test class mixes
 * in TypeCheckedTripleEquals, inside your test class the following methods will be implicit:
 * 
    
 *
 * 
      
 * 
    • convertToCheckingEqualizer
      • 
 * 
    • typeCheckedConstraint
      • 
 * 
    • lowPriorityTypeCheckedConstraint
      • 
 * 
    • convertEquivalenceToAToBConstraint
      • 
 * 
    • convertEquivalenceToBToAConstraint
      • 
 * 
    
 * 
 * 
    
 * If in the body of a test you want to turn off the type checking, you can import the members
 * of TripleEquals in the body of that test. This will not only hide
 * non-implicit methods convertToEqualizer unconstrainedEquality of TypeCheckedTripleEquals,
 * replacing those with implicit ones defined in TripleEquals, it will also hide the three methods made implicit in TypeCheckedTripleEquals
 * (and listed above), replacing them by non-implicit ones.
 * 
    
 * 
 * 
    
 * 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.
 * 
    
 * 
 * @author Bill Venners
 */
trait TripleEqualsSupport {

  /**
   * Class used via an implicit conversion to enable any two objects to be compared with
   * === and !== with a Boolean result and no enforced type constraint between
   * two object types. For example:
   *
   * 
       * assert(a === b)
   * assert(c !== d)
   * 
    
   *
   * 
    
   * You can also check numeric values against another with a tolerance. Here are some examples:
   * 
    
   *
   * 
       * assert(a === (2.0 +- 0.1))
   * assert(c !== (2.0 +- 0.1))
   * 
    
   *
   * @param leftSide An object to convert to Equalizer, which represents the value
   *     on the left side of a === or !== invocation.
   *
   * @author Bill Venners
   */
  class Equalizer[L](val leftSide: L) { // Note: This is called leftSide not left to avoid a conflict with scalaz's implicit that adds left
  
    /**
     * Compare two objects for equality, returning a Boolean, using the Equality type class passed as equality.
     *
     * @param rightSide the object to compare for equality with leftSide, passed to the constructor
     * @param equality an implicit Equality type class that defines a way of calculating equality for objects of type L
     * @return true if the leftSide and rightSide objects are equal according to the passed Equality type class.
     */
    def ===(rightSide: Any)(implicit equality: Equality[L]): Boolean = equality.areEqual(leftSide, rightSide)
  
    /**
     * Compare two objects for inequality, returning a Boolean, using the Equality type class passed as equality.
     *
     * @param rightSide the object to compare for inequality with leftSide, passed to the constructor
     * @param equality an implicit Equality type class that defines a way of calculating equality for objects of type L
     * @return true if the leftSide and rightSide objects are not equal according to the passed Equality type class.
     */
    def !==(rightSide: Any)(implicit equality: Equality[L]): Boolean = !equality.areEqual(leftSide, rightSide)
  
    /**
     * Determine whether a numeric object is within the passed Spread, returning a Boolean.
     *
     * @param spread the Spread against which to compare the value passed to the constructor as leftSide 
     * @return true if the value passed to the constructor as leftSide is within the Spread passed to this method.
     */
    def ===(spread: Spread[L]): Boolean = if (spread != null) spread.isWithin(leftSide) else leftSide == spread
  
    /**
     * Determine whether a numeric object is outside the passed Spread, returning a Boolean.
     *
     * @param spread the Spread against which to compare the value passed to the constructor as leftSide 
     * @return true if the value passed to the constructor as leftSide is not within the Spread passed to this method.
     */
    def !==(spread: Spread[L]): Boolean = if (spread != null) !spread.isWithin(leftSide) else leftSide != spread
  
    /**
     * Determine whether an object reference is null.
     *
     * @param literalNull a null value against which to compare the value passed to the constructor as leftSide for equality
     * @return true if the value passed to the constructor as leftSide is null.
     */
    def ===(literalNull: Null): Boolean = leftSide == null
  
    /**
     * Determines whether an object reference is non-null.
     *
     * @param literalNull a null value against which to compare the value passed to the constructor as leftSide for inequality
     * @return true if the value passed to the constructor as leftSide is non-null.
     */
    def !==(literalNull: Null): Boolean = leftSide != null
  }

  /**
   * Class used via an implicit conversion to enable any two objects to be compared with
   * === and !== with an Option[String] result and no enforced type constraint between
   * two object types. For example:
   *
   * 
       * assert(a === b)
   * assert(c !== d)
   * 
    
   *
   * 
    
   * You can also check numeric values against another with a tolerance. Here are some examples:
   * 
    
   *
   * 
       * assert(a === (2.0 +- 0.1))
   * assert(c !== (2.0 +- 0.1))
   * 
    
   *
   * 
    
   * The benefit of using assert(a === b) rather than assert(a == b) in ScalaTest code is
   * that a TestFailedException produced by the former will include the values of a and b
   * in its detail message.
   * 
    
   *
   * 
    
   * 
   * Note: This class has "Legacy" in its name because its approach to error messages will eventually be replaced by macros. Once ScalaTest no longer supports Scala 2.9, 
   * this class will be deprecated in favor of class Equalizer. Instead of obtaining nice error messages via the Option[String]
   * returned by the methods of this class, the error messages will be obtained by a macro. The "legacy" approach to good error messages will continue to be
   * used, however, until ScalaTest no longer supports Scala 2.9, since macros were introduced to Scala (in experimental form) in 2.10.
   * 
   * 
    
   *
   * 
    
   * The primary constructor takes one object, left, whose type is being converted to Equalizer. The left
   * value may be a null reference, because this is allowed by Scala's == operator.
   * 
    
   *
   * @param left An object to convert to Equalizer, which represents the left value
   *     of a === or !== equality check.
   *
   * @author Bill Venners
   */
  class LegacyEqualizer[L](left: L) {
  
    private def diffStrings(s: String, t: String): Tuple2[String, String] = {
      def findCommonPrefixLength(s: String, t: String): Int = {
        val max = s.length.min(t.length) // the maximum potential size of the prefix
        var i = 0
        var found = false
        while (i < max & !found) {
          found = (s.charAt(i) != t.charAt(i))
          if (!found)
            i = i + 1
        }
        i
      }
      def findCommonSuffixLength(s: String, t: String): Int = {
        val max = s.length.min(t.length) // the maximum potential size of the suffix
        var i = 0
        var found = false
        while (i < max & !found) {
          found = (s.charAt(s.length - 1 - i) != t.charAt(t.length - 1 - i))
          if (!found)
            i = i + 1
        }
        i
      }
      val commonPrefixLength = findCommonPrefixLength(s, t)
      val commonSuffixLength = findCommonSuffixLength(s.substring(commonPrefixLength), t.substring(commonPrefixLength))
      val prefix = s.substring(0, commonPrefixLength)
      val suffix = if (s.length - commonSuffixLength < 0) "" else s.substring(s.length - commonSuffixLength)
      val sMiddleEnd = s.length - commonSuffixLength
      val tMiddleEnd = t.length - commonSuffixLength
      val sMiddle = s.substring(commonPrefixLength, sMiddleEnd)
      val tMiddle = t.substring(commonPrefixLength, tMiddleEnd)
      val MaxContext = 20
      val shortPrefix = if (commonPrefixLength > MaxContext) "..." + prefix.substring(prefix.length - MaxContext) else prefix
      val shortSuffix = if (commonSuffixLength > MaxContext) suffix.substring(0, MaxContext) + "..." else suffix
      (shortPrefix + "[" + sMiddle + "]" + shortSuffix, shortPrefix + "[" + tMiddle + "]" + shortSuffix)
    }
  
    // If the objects are two strings, replace them with whatever is returned by diffStrings.
    // Otherwise, use the same objects.
    private def getObjectsForFailureMessage(a: Any, b: Any) =
      a match {
        case aStr: String => {
          b match {
            case bStr: String => {
              diffStrings(aStr, bStr)
            }
            case _ => (a, b)
          }
        }
        case _ => (a, b)
      }
  
    /**
     * Compare two objects for equality, returning an Option[String], using the Equality type class passed as equality.
     *
     * @param right the object to compare for equality with left, passed to the constructor
     * @param equality an implicit Equality type class that defines a way of calculating equality for objects of type L
     * @return None if the left and right objects are equal according to the passed Equality type class.
     *    else returns an error message string wrapped in a Some.
     */
    def ===(right: Any)(implicit equality: Equality[L]): Option[String] = 
      if (equality.areEqual(left, right))
        None
      else {
        val (leftee, rightee) = getObjectsForFailureMessage(left, right)
        Some(FailureMessages("didNotEqual", leftee, rightee))
      }
  
    /**
     * Compare two objects for inequality, returning an Option[String], using the Equality type class passed as equality.
     *
     * @param right the object to compare for inequality with left, passed to the constructor
     * @param equality an implicit Equality type class that defines a way of calculating equality for objects of type L
     * @return None if the left and right objects are not equal according to the passed Equality type class.
     *    else returns an error message string wrapped in a Some.
     */
    def !==(right: Any)(implicit equality: Equality[L]): Option[String] =
      if (!equality.areEqual(left, right))
        None
      else {
        val (leftee, rightee) = getObjectsForFailureMessage(left, right)
        Some(FailureMessages("equaled", leftee, rightee))
      }
  
    /**
     * Determine whether a numeric object is within the passed Spread, returning an Option[String].
     *
     * @param spread the Spread against which to compare the value passed to the constructor as left 
     * @return None if the value passed to the constructor as left is not within the Spread passed to this method, 
     *    else returns an error message string wrapped in a Some.
     */
    def ===(spread: Spread[L]): Option[String] =
      if (spread == null) {
        if (left == null)
          None
        else {
          val (leftee, rightee) = getObjectsForFailureMessage(left, spread)
          Some(FailureMessages("didNotEqual", leftee, rightee))
        }
      }
      else {
        if (spread.isWithin(left))
          None
        else
          Some(FailureMessages("wasNotPlusOrMinus", left, spread.pivot, spread.tolerance))
      }
  
    /**
     * Determine whether a numeric object is outside the passed Spread, returning an Option[String].
     *
     * @param spread the Spread against which to compare the value passed to the constructor as left 
     * @return true if the value passed to the constructor as left is not within the Spread passed to this method.
     *    else returns an error message string wrapped in a Some.
     */
    def !==(spread: Spread[L]): Option[String] =
      if (spread == null) {
        if (left != null)
          None
        else {
          val (leftee, rightee) = getObjectsForFailureMessage(left, spread)
          Some(FailureMessages("equaled", leftee, rightee))
        }
      }
      else {
        if (if (spread != null) !spread.isWithin(left) else left != spread)
          None
        else
          Some(FailureMessages("wasPlusOrMinus", left, spread.pivot, spread.tolerance))
      }
  }
  
  /**
   * Class used via an implicit conversion to enable two objects to be compared with
   * === and !== with a Boolean result and an enforced type constraint between
   * two object types. For example:
   *
   * 
       * assert(a === b)
   * assert(c !== d)
   * 
    
   *
   * 
    
   * You can also check numeric values against another with a tolerance. Here are some examples:
   * 
    
   *
   * 
       * assert(a === (2.0 +- 0.1))
   * assert(c !== (2.0 +- 0.1))
   * 
    
   *
   * @param leftSide An object to convert to Equalizer, which represents the value
   *     on the left side of a === or !== invocation.
   *
   * @author Bill Venners
   */
  class CheckingEqualizer[L](val leftSide: L) { // Note: This is called leftSide not left to avoid a conflict with scalaz's implicit that adds left
  
    /**
     * Compare two objects for equality, returning a Boolean, using the Constraint instance passed as constraint.
     *
     * @param rightSide the object to compare for equality with leftSide, passed to the constructor
     * @param constraint an implicit Constraint instance that enforces a relationship between types L and R and
     *    defines a way of calculating equality for objects of type L
     * @return true if the leftSide and rightSide objects are equal according to the passed Constraint instance.
     */
    def ===[R](rightSide: R)(implicit constraint: Constraint[L, R]): Boolean = constraint.areEqual(leftSide, rightSide)
  
    /**
     * Compare two objects for inequality, returning a Boolean, using the Constraint instance passed as constraint.
     *
     * @param rightSide the object to compare for inequality with leftSide, passed to the constructor
     * @param constraint an implicit Constraint instance that enforces a relationship between types L and R and
     *    defines a way of calculating equality for objects of type L
     * @return true if the leftSide and rightSide objects are not equal according to the passed Constraint instance.
     */
    def !==[R](rightSide: R)(implicit constraint: Constraint[L, R]): Boolean = !constraint.areEqual(leftSide, rightSide)
  
    /**
     * Determine whether a numeric object is within the passed Spread, returning a Boolean.
     *
     * @param spread the Spread against which to compare the value passed to the constructor as leftSide 
     * @return true if the value passed to the constructor as leftSide is not within the Spread passed to this method.
     */
    def ===(spread: Spread[L]): Boolean = if (spread != null) spread.isWithin(leftSide) else leftSide == spread
  
    /**
     * Determine whether a numeric object is outside the passed Spread, returning a Boolean.
     *
     * @param spread the Spread against which to compare the value passed to the constructor as leftSide 
     * @return true if the value passed to the constructor as leftSide is not within the Spread passed to this method.
     */
    def !==(spread: Spread[L]): Boolean = if (spread != null) !spread.isWithin(leftSide) else leftSide != spread
  }

  /**
   * Class used via an implicit conversion to enable any two objects to be compared with
   * === and !== with an Option[String] result and an enforced type constraint between
   * two object types. For example:
   *
   * 
       * assert(a === b)
   * assert(c !== d)
   * 
    
   *
   * 
    
   * You can also check numeric values against another with a tolerance. Here are some examples:
   * 
    
   *
   * 
       * assert(a === (2.0 +- 0.1))
   * assert(c !== (2.0 +- 0.1))
   * 
    
   *
   * 
    
   * The benefit of using assert(a === b) rather than assert(a == b) in ScalaTest code is
   * that a TestFailedException produced by the former will include the values of a and b
   * in its detail message.
   * 
    
   *
   * 
    
   * 
   * Note: This class has "Legacy" in its name because its approach to error messages will eventually be replaced by macros. Once ScalaTest no longer supports Scala 2.9, 
   * this class will be deprecated in favor of class Equalizer. Instead of obtaining nice error messages via the Option[String]
   * returned by the methods of this class, the error messages will be obtained by a macro. The "legacy" approach to good error messages will continue to be
   * used, however, until ScalaTest no longer supports Scala 2.9, since macros were introduced to Scala (in experimental form) in 2.10.
   * 
   * 
    
   *
   * 
    
   * The primary constructor takes one object, left, whose type is being converted to Equalizer. The left
   * value may be a null reference, because this is allowed by Scala's == operator.
   * 
    
   *
   * @param left An object to convert to Equalizer, which represents the left value
   *     of a === or !== equality check.
   *
   * @author Bill Venners
   */
  class LegacyCheckingEqualizer[L](left: L) {
  
    private def diffStrings(s: String, t: String): Tuple2[String, String] = {
      def findCommonPrefixLength(s: String, t: String): Int = {
        val max = s.length.min(t.length) // the maximum potential size of the prefix
        var i = 0
        var found = false
        while (i < max & !found) {
          found = (s.charAt(i) != t.charAt(i))
          if (!found)
            i = i + 1
        }
        i
      }
      def findCommonSuffixLength(s: String, t: String): Int = {
        val max = s.length.min(t.length) // the maximum potential size of the suffix
        var i = 0
        var found = false
        while (i < max & !found) {
          found = (s.charAt(s.length - 1 - i) != t.charAt(t.length - 1 - i))
          if (!found)
            i = i + 1
        }
        i
      }
      val commonPrefixLength = findCommonPrefixLength(s, t)
      val commonSuffixLength = findCommonSuffixLength(s.substring(commonPrefixLength), t.substring(commonPrefixLength))
      val prefix = s.substring(0, commonPrefixLength)
      val suffix = if (s.length - commonSuffixLength < 0) "" else s.substring(s.length - commonSuffixLength)
      val sMiddleEnd = s.length - commonSuffixLength
      val tMiddleEnd = t.length - commonSuffixLength
      val sMiddle = s.substring(commonPrefixLength, sMiddleEnd)
      val tMiddle = t.substring(commonPrefixLength, tMiddleEnd)
      val MaxContext = 20
      val shortPrefix = if (commonPrefixLength > MaxContext) "..." + prefix.substring(prefix.length - MaxContext) else prefix
      val shortSuffix = if (commonSuffixLength > MaxContext) suffix.substring(0, MaxContext) + "..." else suffix
      (shortPrefix + "[" + sMiddle + "]" + shortSuffix, shortPrefix + "[" + tMiddle + "]" + shortSuffix)
    }
  
    // If the objects are two strings, replace them with whatever is returned by diffStrings.
    // Otherwise, use the same objects.
    private def getObjectsForFailureMessage(a: Any, b: Any) =
      a match {
        case aStr: String => {
          b match {
            case bStr: String => {
              diffStrings(aStr, bStr)
            }
            case _ => (a, b)
          }
        }
        case _ => (a, b)
      }
  
    /**
     * Compare two objects for equality, returning an Option[String], using the Constraint instance passed as constraint.
     *
     * @param right the object to compare for equality with left, passed to the constructor
     * @param constraint an implicit Constraint instance that enforces a relationship between types L and R and
     *    defines a way of calculating equality for objects of type L
     * @return None if the left and right objects are equal according to the passed Equality type class.
     *    else returns an error message string wrapped in a Some.
     */
    def ===[R](right: R)(implicit constraint: Constraint[L, R]): Option[String] = 
      if (constraint.areEqual(left, right))
        None
      else {
        val (leftee, rightee) = getObjectsForFailureMessage(left, right)
        Some(FailureMessages("didNotEqual", leftee, rightee))
      }
  
    /**
     * Compare two objects for inequality, returning an Option[String], using the Constraint instance passed as constraint.
     *
     * @param right the object to compare for inequality with left, passed to the constructor
     * @param constraint an implicit Constraint instance that enforces a relationship between types L and R and
     *    defines a way of calculating equality for objects of type L
     * @return None if the left and right objects are not equal according to the passed Equality type class.
     *    else returns an error message string wrapped in a Some.
     */
    def !==[R](right: R)(implicit constraint: Constraint[L, R]): Option[String] =
      if (!constraint.areEqual(left, right))
        None
      else {
        val (leftee, rightee) = getObjectsForFailureMessage(left, right)
        Some(FailureMessages("equaled", leftee, rightee))
      }
  
    /**
     * Determine whether a numeric object is within the passed Spread, returning an Option[String].
     *
     * @param spread the Spread against which to compare the value passed to the constructor as left 
     * @return None if the value passed to the constructor as left is not within the Spread passed to this method, 
     *    else returns an error message string wrapped in a Some.
     */
    def ===(spread: Spread[L]): Option[String] =
      if (spread == null) {
        if (left == null)
          None
        else {
          val (leftee, rightee) = getObjectsForFailureMessage(left, spread)
          Some(FailureMessages("equaled", leftee, rightee))
        }
      }
      else {
        if (spread.isWithin(left))
          None
        else
          Some(FailureMessages("wasNotPlusOrMinus", left, spread.pivot, spread.tolerance))
      }
  
    /**
     * Determine whether a numeric object is outside the passed Spread, returning an Option[String].
     *
     * @param spread the Spread against which to compare the value passed to the constructor as left 
     * @return true if the value passed to the constructor as left is not within the Spread passed to this method.
     *    else returns an error message string wrapped in a Some.
     */
    def !==(spread: Spread[L]): Option[String] =
      if (spread == null) {
        if (left != null)
          None
        else {
          val (leftee, rightee) = getObjectsForFailureMessage(left, spread)
          Some(FailureMessages("equaled", leftee, rightee))
        }
      }
      else {
        if (if (spread != null) !spread.isWithin(left) else left != spread)
          None
        else
          Some(FailureMessages("wasPlusOrMinus", left, spread.pivot, spread.tolerance))
      }
  }

  /**
   * Returns an Equality[A] for any type A that determines equality
   * by first calling .deep on any Array (on either the left or right side),
   * then comparing the resulting objects with ==.
   *
   * @return a default Equality for type A
   */
  def defaultEquality[A]: Equality[A] = Equality.default

  /**
   * Converts to an Equalizer that provides === and !== operators that
   * result in Boolean and enforce no type constraint.
   *
   * 
    
   * This method is overridden and made implicit by subtrait TripleEquals and overriden as non-implicit by the other
   * subtraits in this package.
   * 
    
   *
   * @param left the object whose type to convert to Equalizer.
   * @throws NullPointerException if left is null.
   */
  def convertToEqualizer[T](left: T): Equalizer[T]

  /**
   * Converts to a LegacyEqualizer that provides === and !== operators that
   * result in Option[String] and enforce no type constraint.
   *
   * 
    
   * This method is overridden and made implicit by subtrait LegacyTripleEquals and overriden as non-implicit
   * by the other subtraits in this package.
   * 
    
   *
   * @param left the object whose type to convert to LegacyEqualizer.
   * @throws NullPointerException if left is null.
   */
  def convertToLegacyEqualizer[T](left: T): LegacyEqualizer[T]

  /**
   * Converts to an CheckingEqualizer that provides === and !== operators
   * that result in Boolean and enforce a type constraint.
   *
   * 
    
   * This method is overridden and made implicit by subtraits TypeCheckedTripleEquals and
   * ConversionCheckedTripleEquals, and overriden as
   * non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param left the object whose type to convert to CheckingEqualizer.
   * @throws NullPointerException if left is null.
   */
  def convertToCheckingEqualizer[T](left: T): CheckingEqualizer[T]

  /**
   * Converts to a LegacyCheckingEqualizer that provides === and !== operators
   * that result in Option[String] and enforce a type constraint.
   *
   * 
    
   * This method is overridden and made implicit by subtraits TypeCheckedLegacyTripleEquals
   * and ConversionCheckedLegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param left the object whose type to convert to LegacyCheckingEqualizer.
   * @throws NullPointerException if left is null.
   */
  def convertToLegacyCheckingEqualizer[T](left: T): LegacyCheckingEqualizer[T]

  /**
   * Provides a Constraint[A, B] class for any two types A and B, with no type constraint enforced, given an
   * implicit Equality[A].
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equality[A]'s
   * areEqual method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits TripleEquals and
   * LegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equalityOfA an Equality[A] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @return a Constraint[A, B] whose areEqual method delegates to the areEqual method of
   *     the passed Equality[A].
   */
  def unconstrainedEquality[A, B](implicit equalityOfA: Equality[A]): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
   * that A must be a subtype of B, given an implicit Equivalence[B].
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * LowPriorityTypeCheckedConstraint (extended by
   * TypeCheckedTripleEquals), and
   * LowPriorityTypeCheckedLegacyConstraint (extended by
   * TypeCheckedLegacyTripleEquals), and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equivalenceOfB an Equivalence[B] type class to which the Constraint.areEqual method
   *    will delegate to determine equality.
   * @param ev evidence that A is a subype of     B
   * @return a Constraint[A, B] whose areEqual method delegates to the
   * areEquivalent method of the passed Equivalence[B].
   */
  def lowPriorityTypeCheckedConstraint[A, B](implicit equivalenceOfB: Equivalence[B], ev: A <:< B): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
   * that A must be a subtype of B, given an explicit Equivalence[B].
   *
   * 
    
   * This method is used to enable the Explicitly DSL for
   * TypeCheckedTripleEquals by requiring an explicit Equivalance[B], but
   * taking an implicit function that provides evidence that A is a subtype of B.
   * 
    
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * LowPriorityTypeCheckedConstraint (extended by
   * TypeCheckedTripleEquals), and
   * LowPriorityTypeCheckedLegacyConstraint (extended by
   * TypeCheckedLegacyTripleEquals), and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equivalenceOfB an Equivalence[B] type class to which the Constraint.areEqual method
   *    will delegate to determine equality.
   * @param ev evidence that A is a subype of B
   * @return a Constraint[A, B] whose areEqual method delegates to the
   * areEquivalent method of the passed Equivalence[B].
   */
  def convertEquivalenceToAToBConstraint[A, B](equivalenceOfB: Equivalence[B])(implicit ev: A <:< B): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
   * that B must be a subtype of A, given an implicit Equivalence[A].
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * TypeCheckedTripleEquals) and
   * TypeCheckedLegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equalityOfA an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param ev evidence that B is a subype of A
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[A].
   */
  def typeCheckedConstraint[A, B](implicit equivalenceOfA: Equivalence[A], ev: B <:< A): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] for any two types A and B, enforcing the type constraint
   * that B must be a subtype of A, given an explicit Equivalence[A].
   *
   * 
    
   * This method is used to enable the Explicitly DSL for
   * TypeCheckedTripleEquals by requiring an explicit Equivalance[B], but
   * taking an implicit function that provides evidence that A is a subtype of B. For example, under TypeCheckedTripleEquals,
   * this method (as an implicit method), would be used to compile this statement:
   * 
    
   *
   * 
       * def closeEnoughTo1(num: Double): Boolean =
   *   (num === 1.0)(decided by forgivingEquality)
   * 
    
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * TypeCheckedTripleEquals) and
   * TypeCheckedLegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equalityOfA an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param ev evidence that B is a subype of A
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[A].
   */
  def convertEquivalenceToBToAConstraint[A, B](equivalenceOfA: Equivalence[A])(implicit ev: B <:< A): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
   * implicitly convertible to B, given an implicit Equivalence[B].
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * LowPriorityConversionCheckedConstraint (extended by
   * ConversionCheckedTripleEquals), and
   * LowPriorityConversionCheckedLegacyConstraint (extended by
   * ConversionCheckedLegacyTripleEquals), and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equalityOfB an Equivalence[B] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param cnv an implicit conversion from A to B
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[B].
   */
  def lowPriorityConversionCheckedConstraint[A, B](implicit equivalenceOfB: Equivalence[B], cnv: A => B): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that A is
   * implicitly convertible to B, given an explicit Equivalence[B].
   *
   * 
    
   * This method is used to enable the Explicitly DSL for
   * ConversionCheckedTripleEquals by requiring an explicit Equivalance[B], but
   * taking an implicit function that converts from A to B.
   * 
    
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[B]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * LowPriorityConversionCheckedConstraint (extended by
   * ConversionCheckedTripleEquals), and
   * LowPriorityConversionCheckedLegacyConstraint (extended by
   * ConversionCheckedLegacyTripleEquals), and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equalityOfB an Equivalence[B] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param cnv an implicit conversion from A to B
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[B].
   */
  def convertEquivalenceToAToBConversionConstraint[A, B](equivalenceOfB: Equivalence[B])(implicit ev: A => B): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
   * implicitly convertible to A, given an implicit Equivalence[A].
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * ConversionCheckedTripleEquals) and
   * ConversionCheckedLegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equivalenceOfA an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param cnv an implicit conversion from B to A
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[A].
   */
  def conversionCheckedConstraint[A, B](implicit equivalenceOfA: Equivalence[A], cnv: B => A): Constraint[A, B]

  /**
   * Provides a Constraint[A, B] class for any two types A and B, enforcing the type constraint that B is
   * implicitly convertible to A, given an explicit Equivalence[A].
   *
   * 
    
   * This method is used to enable the Explicitly DSL for
   * ConversionCheckedTripleEquals by requiring an explicit Equivalance[A], but
   * taking an implicit function that converts from B to A. For example, under ConversionCheckedTripleEquals,
   * this method (as an implicit method), would be used to compile this statement:
   * 
    
   *
   * 
       * def closeEnoughTo1(num: Double): Boolean =
   *   (num === 1.0)(decided by forgivingEquality)
   * 
    
   *
   * 
    
   * The returned Constraint's areEqual method uses the implicitly passed Equivalence[A]'s
   * areEquivalent method to determine equality.
   * 
    
   *
   * 
    
   * This method is overridden and made implicit by subtraits
   * ConversionCheckedTripleEquals) and
   * ConversionCheckedLegacyTripleEquals, and
   * overriden as non-implicit by the other subtraits in this package.
   * 
    
   *
   * @param equivalenceOfA an Equivalence[A] type class to which the Constraint.areEqual method will delegate to determine equality.
   * @param cnv an implicit conversion from B to A
   * @return a Constraint[A, B] whose areEqual method delegates to the areEquivalent method of
   *     the passed Equivalence[A].
   */
  def convertEquivalenceToBToAConversionConstraint[A, B](equivalenceOfA: Equivalence[A])(implicit ev: B => A): Constraint[A, B]

  /**
   * Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
   * the “<left> should === <right>” syntax
   * of Matchers.
   *
   * @param right the right-hand side value for an equality assertion
   * @return a TripleEqualsInvocation wrapping the passed right value, with expectingEqual
   *    set to true.
   */
  def ===[T](right: T): TripleEqualsInvocation[T] = new TripleEqualsInvocation[T](right, true)

  /**
   * Returns a TripleEqualsInvocation[T], given an object of type T, to facilitate
   * the “<left> should !== <right>” syntax
   * of Matchers.
   *
   * @param right the right-hand side value for an equality assertion
   * @return a TripleEqualsInvocation wrapping the passed right value, with expectingEqual
   *    set to false.
   */
  def !==[T](right: T): TripleEqualsInvocation[T] = new TripleEqualsInvocation[T](right, false)

  /**
   * Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
   * the “<left> should === null” syntax
   * of Matchers.
   *
   * @param right a null reference
   * @return a TripleEqualsInvocation wrapping the passed null value, with expectingEqual
   *    set to true.
   */
  def ===(right: Null): TripleEqualsInvocation[Null] = new TripleEqualsInvocation[Null](right, true)

  /**
   * Returns a TripleEqualsInvocation[Null], given a null reference, to facilitate
   * the “<left> should !== null” syntax
   * of Matchers.
   *
   * @param right a null reference
   * @return a TripleEqualsInvocation wrapping the passed null value, with expectingEqual
   *    set to false.
   */
  def !==(right: Null): TripleEqualsInvocation[Null] = new TripleEqualsInvocation[Null](right, false)

  /**
   * Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
   * the “<left> should === (<pivot> +- <tolerance>)”
   * syntax of Matchers.
   *
   * @param right the Spread[T] against which to compare the left-hand value
   * @return a TripleEqualsInvocationOnSpread wrapping the passed Spread[T] value, with
   * expectingEqual set to true.
   */
  def ===[T](right: Spread[T]): TripleEqualsInvocationOnSpread[T] = new TripleEqualsInvocationOnSpread[T](right, true)

  /**
   * Returns a TripleEqualsInvocationOnSpread[T], given an Spread[T], to facilitate
   * the “<left> should !== (<pivot> +- <tolerance>)”
   * syntax of Matchers.
   *
   * @param right the Spread[T] against which to compare the left-hand value
   * @return a TripleEqualsInvocationOnSpread wrapping the passed Spread[T] value, with
   * expectingEqual set to false.
   */
  def !==[T](right: Spread[T]): TripleEqualsInvocationOnSpread[T] = new TripleEqualsInvocationOnSpread[T](right, false)
}

object TripleEqualsSupport {

  /**
   * An implementation of Constraint for two types A and B that requires an Equality[A] to
   * which its areEqual method can delegate an equality comparison.
   *
   * @param equalityOfA an Equality type class for A
   */
  final class EqualityConstraint[A, B](equalityOfA: Equality[A]) extends Constraint[A, B] {

    /**
     * Indicates whether the objects passed as a and b are equal by returning the
     * result of invoking areEqual(a, b) on the passed equalityOfA object.
     *
     * @param a a left-hand-side object being compared with another (right-hand-side one) for equality (e.g., a == b)
     * @param b a right-hand-side object being compared with another (left-hand-side one) for equality (e.g., a == b)
     */
    def areEqual(a: A, b: B): Boolean = equalityOfA.areEqual(a, b)
  }

  /**
   * An implementation of Constraint for two types A and B that requires an Equality[B]
   * and a conversion function from A to B. 
   *
   * @param equivalenceOfB an Equivalence type class for B
   */
  final class AToBEquivalenceConstraint[A, B](equivalenceOfB: Equivalence[B], cnv: A => B) extends Constraint[A, B] {

    /**
     * Indicates whether the objects passed as a and b are equal by return the
     * result of invoking areEqual(cnv(a), b) on the passed equalityOfB object.
     *
     * 
    
     * In other words, the a object of type A is first converted to a B via the passed conversion
     * function, cnv, then compared for equality with the b object.
     * 
    
     *
     * @param a a left-hand-side object being compared with another (right-hand-side one) for equality (e.g., a == b)
     * @param b a right-hand-side object being compared with another (left-hand-side one) for equality (e.g., a == b)
     */
    override def areEqual(a: A, b: B): Boolean = equivalenceOfB.areEquivalent(cnv(a), b)
  }
  
  /**
   * An implementation of Constraint for two types A and B that requires an Equality[A]
   * and a conversion function from B to A. 
   *
   * @param equivalenceOfA an Equivalence type class for A
   */
  final class BToAEquivalenceConstraint[A, B](equivalenceOfA: Equivalence[A], cnv: B => A) extends Constraint[A, B] {
  
    /**
     * Indicates whether the objects passed as a and b are equal by returning the
     * result of invoking areEqual(a, cnv(b)) on the passed equalityOfA object.
     *
     * 
    
     * In other words, the b object of type B is first converted to an A via the passed conversion
     * function, cnv, then compared for equality with the a object.
     * 
    
     *
     * @param a a left-hand-side object being compared with another (right-hand-side one) for equality (e.g., a == b)
     * @param b a right-hand-side object being compared with another (left-hand-side one) for equality (e.g., a == b)
     */
    override def areEqual(a: A, b: B): Boolean = equivalenceOfA.areEquivalent(a, cnv(b))
  }

  /**
   * Facilitates the “should === (x += y)” and  “should !== (x += y)” syntax of ScalaTest's matchers DSL. 
   *  
   * 
    
   * Instances of this class are created and returned by the === and !== methods of
   * trait TripleEqualsSupport.
   * 
    
   *
   * @param spread the Spread[T] against which to compare the left-hand value
   * @param expectingEqual true if the result of a === invocation; false if the result of a !== invocation.
   */
  final case class TripleEqualsInvocationOnSpread[T](spread: Spread[T], expectingEqual: Boolean)
  
  /**
   * Facilitates the “should ===” and  “should !==” syntax of ScalaTest's matchers DSL. 
   *  
   * 
    
   * Instances of this class are created and returned by the === and !== methods of
   * trait TripleEqualsSupport.
   * 
    
   *
   * @param right the right-hand side value for an equality assertion
   * @param expectingEqual true if the result of a === invocation; false if the result of a !== invocation.
   */
  final case class TripleEqualsInvocation[T](right: T, expectingEqual: Boolean) {
    override def toString: String = (if (expectingEqual) "===" else "!==") + " " + Prettifier.default(right)
  }

  /**
   * Class representing an spread (i.e., range) between two numbers.
   * 
   * 
    
   * The spread is expressed in terms of a Numeric pivot and tolerance.
   * The spread extends from pivot - tolerance to pivot + tolerance, inclusive.
   * 
    
   * 
   * @param pivot the pivot number at the center of the spread
   * @param tolerance the tolerance that determines the high and low point of the spread
   * 
   * @author Bill Venners
   */
  final case class Spread[T : Numeric](pivot: T, tolerance: T) {
  
    private val numeric = implicitly[Numeric[T]]
  
    require(numeric.signum(tolerance) >= 0, "tolerance must be zero or greater, but was " + tolerance)
  
    private val max = numeric.plus(pivot, tolerance)
    private val min = numeric.minus(pivot, tolerance)
  
    /**
     * Determines whether the passed Numeric value n is within the spread represented
     * by this Spread instance.
     */
    def isWithin(n: T): Boolean = {
      numeric.gteq(n, min) && numeric.lteq(n, max)
    }
  
    /**
     * Returns true if the passed number, n, is within the spread represented by this Spread instance
     *
     * 
    
     * The purpose of this method, which will likely be used only rarely, is to achieve symmetry around the === operator. The
     * TripleEquals trait (and its type-checking siblings TypeCheckedTripleEquals and ConversionCheckedTripleEquals) enable you to write:
     * 
    
     *
     * 
         * a === (1.0 +- 0.1)
     * 
    
     *
     * 
    
     * This method ensures the following mirrored form means the same thing:
     * 
    
     *
     * 
         * (1.0 +- 0.1) === a
     * 
    
     *
     * @param n a number that may or may not lie within this spread
     */
    def ===(n: T): Boolean = isWithin(n)
  
    /**
     * Returns false if the passed number, n, is within the spread represented by this Spread instance
     *
     * 
    
     * The purpose of this method, which will likely be used only rarely, is to achieve symmetry around the !== operator. The
     * TripleEquals trait (and its type-checking siblings TypeCheckedTripleEquals and ConversionCheckedTripleEquals) enable you to write:
     * 
    
     *
     * 
         * a !== (1.0 +- 0.1)
     * 
    
     *
     * 
    
     * This method ensures the following mirrored form means the same thing:
     * 
    
     *
     * 
         * (1.0 +- 0.1) !== a
     * 
    
     *
     * @param n a number that may or may not lie within this spread
     */
    def !==(n: T): Boolean = !isWithin(n)
    
    /**
     * Overrides toString to return "[pivot] plusOrMinus [tolerance]"
     */
    override def toString: String = Prettifier.default(pivot) + " +- " + Prettifier.default(tolerance)
  }
}




    © 2015 - 2024 Weber Informatics LLC | Privacy Policy