org.scalactic.NormalizingEquivalence.scala Maven / Gradle / Ivy
/*
* 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.scalactic
/**
* An Equivalence[A] implementation that determines the equality of two objects by normalizing
* one or both objects, then comparing the results using an “after normalization” Equivalence referenced from
* the afterNormalizationEquivalence member. By default, the afterNormalizationEquivalence is
* an instance of Equivalence.default[A].
*
*
*
* NormalizingEquivalence is returned by the Explicitly DSL's “after being”
* syntax, using for the afterNormalizationEquivalence the implicit Equivalence in scope for the type
* of Normalization passed to being. Here's an example:
*
*
*
* scala> import org.scalactic._
* import org.scalactic._
*
* scala> import Explicitly._
* import Explicitly._
*
* scala> val lowerCased: Normalization[String] = StringNormalizations.lowerCased
* lowerCased: org.scalactic.Normalization[String] = lowerCased
*
* scala> after being lowerCased
* res0: org.scalactic.NormalizingEquivalence[String] = ComposedNormalizingEquivalence(Equality.default,lowerCased)
*
*/
trait NormalizingEquivalence[A] extends Equivalence[A] { thisNormEq =>
/**
* The Equivalence with which to determine equality after normalizing the left-hand and right-hand values.
*
*
* In this trait's implementation, this val is initialized with the result of invoking Equivalence.default[A].
* Thus default Equivalence is the default afterNormalizationEquivalence. This may be changed by overriding
* afterNormalizationEquivalence in subclasses.
*
*/
val afterNormalizationEquivalence: Equivalence[A] = Equivalence.default[A]
/**
* Determines the equality of two objects by normalizing the left-hand value, a, and the right-hand
* value, b, then passing them to areEquivalent method of afterNormalizationEquivalence.
*
*
* Both the left-hand value, a, and right-hand value, b, are normalized by passing them to the normalized method of this
* NormalizingEquivalence.
*
*/
final def areEquivalent(a: A, b: A): Boolean = {
afterNormalizationEquivalence.areEquivalent(normalized(a), normalized(b))
}
/**
* Returns a normalized form of the passed object.
*
*
* If the passed object is already in normal form, this method may return the same instance passed.
*
*
* @tparam A the type of the object to normalize
* @param a the object to normalize
* @return the normalized form of the passed object
*/
infix
def normalized(a: A): A
/**
* Returns a new NormalizingEquivalence that combines this and the passed Normalization.
*
*
* The normalized method of the NormalizingEquivalence's returned by this method returns a result
* obtained by forwarding the passed value first to this NormalizingEquivalence's implementation of the method,
* then passing that result to the passed Normalization's implementation of the method.
* Essentially, the body of the composed normalized method is:
*
*
*
* uniformityPassedToAnd.normalized(uniformityOnWhichAndWasInvoked.normalized(a))
*
*
* @param other a Normalization to 'and' with this one
* @return a NormalizingEquivalence representing the composition of this and the passed Normalization
*/
infix
final def and(other: Normalization[A]): NormalizingEquivalence[A] =
new ComposedNormalizingEquivalence[A](afterNormalizationEquivalence, this.toNormalization and other)
/**
* Converts this NormalizingEquivalence to a Normalization.
*
* @return a Normalization whose normalized method
* is implemented by forwarding to the normalized method of this NormalizingEquivalence.
*/
final def toNormalization: Normalization[A] =
new Normalization[A] {
def normalized(a: A): A = thisNormEq.normalized(a)
}
}