org.scalautils.Interval.scala Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of scalatest_2.9.1 Show documentation
ScalaTest is a free, open-source testing toolkit for Scala and Java programmers.
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

/**
 * Class representing an interval (i.e., range) between two numbers.
 * 
 * 
 * The interval is expressed in terms of a Numeric pivot and tolerance.
 * The interval extends from pivot - tolerance to pivot + tolerance, inclusive.
 * 
 * 
 * @param pivot the pivot number at the center of the interval
 * @param tolerance the tolerance that determines the high and low point of the interval
 * 
 * @author Bill Venners
 */
final case class Interval[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 interval represented
   * by this Interval instance.
   */
  def isWithin(n: T): Boolean = {
    numeric.gteq(n, min) && numeric.lteq(n, max)
  }

  /**
   * Returns true if the passed number, n, is within the interval represented by this Interval 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 interval
   */
  def ===(n: T): Boolean = isWithin(n)

  /**
   * Returns false if the passed number, n, is within the interval represented by this Interval 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 interval
   */
  def !==(n: T): Boolean = !isWithin(n)
}