feat: config and approximate equality (#19)

Establishes a global config object for a TypeDispatcher instance, so far
  with just properties representing comparison tolerances. Begins a
  "relational" group of functions with basic approximate equality, and
  an initial primitive ordering comparison. Ensures that methods that
  depend on properties of `config` will be properly updated when those
  properties change.

Reviewed-on: #19
Co-authored-by: Glen Whitney <glen@studioinfinity.org>
Co-committed-by: Glen Whitney <glen@studioinfinity.org>

src/generic/__test__/relational.spec.js

@@ -0,0 +1,82 @@
+import assert from 'assert'
+import math from '#nanomath'
+import * as numbers from '#number/all.js'
+import * as generics from '#generic/all.js'
+import {ResolutionError} from '#core/helpers.js'
+import {TypeDispatcher} from '#core/TypeDispatcher.js'
+
+describe('generic relational functions', () => {
+   it('tests equality for anything, approx on numbers', () => {
+      const {equal} = math
+      assert(equal(undefined, undefined))
+      assert(equal(math.types.NumberT, math.types.NumberT))
+      assert(!equal(math.types.NumberT, math.types.BooleanT))
+      assert(!equal(undefined, math.types.NumberT))
+      assert(equal(1, 1))
+      assert(equal(true, 1)) // questionable but same as mathjs
+      assert(!equal(undefined, true))
+      assert(equal(1, 1 + 0.9e-12))
+      assert(equal(0, 1e-16))
+      assert(!equal(1, 1 + 1.1e-12))
+      assert(!equal(0, 1.1e-15))
+   })
+   it('adjusts equality when config changes', () => {
+      const jn = new TypeDispatcher(generics, numbers)
+      const {equal} = jn
+      assert.strictEqual(equal(1, 1 + 0.9e-12), 1)
+      assert.strictEqual(equal(0, 1e-16), 1)
+      assert.strictEqual(equal(1, 1 + 1.1e-12), 0)
+      assert.strictEqual(equal(0, 1.1e-15), 0)
+
+      jn.config.relTol = 1e-10
+      assert.strictEqual(equal(1, 1 + 1.1e-12), 1)
+      assert.strictEqual(equal(1, 1 + 1.1e-10), 0)
+      assert.strictEqual(equal(0, 1.1e-15), 0)
+
+      jn.config.absTol = 1e-13
+      assert.strictEqual(equal(1, 1 + 1.1e-12), 1)
+      assert.strictEqual(equal(1, 1 + 1.1e-10), 0)
+      assert.strictEqual(equal(0, 1.1e-15), 1)
+      assert.strictEqual(equal(0, 1.1e-13), 0)
+   })
+   it('performs three-way comparison', () => {
+      const {compare} = math
+      assert.strictEqual(compare(-0.4e-15, +0.4e-15), 0)
+      assert.strictEqual(compare(2.2, true), 1)
+      assert.strictEqual(compare(-Infinity, 7), -1)
+      assert(isNaN(compare(NaN, 0)))
+      assert.throws(() => compare(false, NaN), TypeError)
+      assert(isNaN(compare(NaN, NaN)))
+      assert.throws(() => compare(true, false), TypeError)
+      assert.throws(() => compare(undefined, -1), ResolutionError)
+   })
+   it('determines the sign of numeric values', () => {
+      const {sign} = math
+      assert.strictEqual(sign(-8e-16), 0)
+      assert.strictEqual(sign(Infinity), 1)
+      assert.strictEqual(sign(-8e-14), -1)
+      assert(isNaN(sign(NaN)))
+      assert.throws(() => sign(false), TypeError)
+      assert.throws(() => sign(undefined), ResolutionError)
+   })
+   it('computes inequalities', () => {
+      const {unequal, larger, largerEq, smaller, smallerEq} = math
+      assert(!unequal(undefined, undefined))
+      assert(!unequal(math.types.NumberT, math.types.NumberT))
+      assert(unequal(math.types.NumberT, math.types.BooleanT))
+      assert(unequal(undefined, math.types.NumberT))
+      assert(!unequal(1, 1))
+      assert(!unequal(true, 1)) // questionable but same as mathjs
+      assert(unequal(undefined, true))
+      assert(!unequal(1, 1 + 0.9e-12))
+      assert(!unequal(0, 1e-16))
+      assert(unequal(1, 1 + 1.1e-12))
+      assert(unequal(0, 1.1e-15))
+      assert(larger(true, 0.5))
+      assert(!larger(3 + 1e-16, 3))
+      assert(largerEq(0.5, false))
+      assert(largerEq(3 + 1e-16, 3))
+      assert(smallerEq(3 + 1e-16, 3))
+      assert(!smaller(3, 3 + 1e-16))
+   })
+})

src/generic/__test__/utils.spec.js

@@ -0,0 +1,13 @@
+import assert from 'assert'
+import math from '#nanomath'
+
+describe('generic utility functions', () => {
+   it('tests whether an element is zero', () => {
+      const {isZero} = math
+      assert(!isZero(3))
+      assert(isZero(3e-16))
+      assert(isZero(false))
+      assert(!isZero(true))
+      assert(isZero(undefined))
+   })
+})

src/generic/all.js

@@ -1 +1,4 @@
 export * as arithmetic from './arithmetic.js'
+export * as configuration from './config.js'
+export * as relational from './relational.js'
+export * as utilities from './utils.js'

src/generic/config.js

@@ -0,0 +1,5 @@
+import {ImplementationsGenerator, onType} from '#core/helpers.js'
+import {Passthru} from '#core/TypePatterns.js'
+
+export const config = new ImplementationsGenerator(
+    () => onType(Passthru, {relTol: 1e-12, absTol: 1e-15}))

src/generic/helpers.js

@@ -0,0 +1 @@
+export const ReturnsAs = (g, f) => (f.returns = g.returns, f)

src/generic/relational.js

@@ -0,0 +1,106 @@
+import {ReturnsAs} from './helpers.js'
+import {onType} from '#core/helpers.js'
+import {Returns} from '#core/Type.js'
+import {Any, matched} from '#core/TypePatterns.js'
+import {boolnum} from '#number/helpers.js'
+
+export const equal = onType([Any, Any], (math, [T, U]) => {
+   // Finding the correct signature of `indistinguishable` to use for
+   // testing (approximate) equality is tricky, because T or U might
+   // need to be converted for the sake of comparison, and some types
+   // allow tolerances for equality and others don't. So the plan is
+   // we first look up without tolerances, then we check the config for
+   // the matching type, and then we look up with tolerances.
+   let exactChecker
+   try {
+      exactChecker = math.indistinguishable.resolve([T, U])
+   } catch { // can't compare, so no way they can be equal
+      return boolnum(() => false)(math)
+   }
+   // Get the type of the first argument to the matching checker:
+   const ByType = matched(exactChecker.template).flat()[0]
+   // Now see if there are tolerances for that type:
+   const typeConfig = math.resolve('config', [ByType])
+   if ('relTol' in typeConfig) {
+      try {
+         const {relTol, absTol} = typeConfig
+         const RT = math.typeOf(relTol)
+         const AT = math.typeOf(absTol)
+         const approx = math.indistinguishable.resolve([T, U, RT, AT])
+         return ReturnsAs(
+            approx, (t, u) => approx(t, u, relTol, absTol))
+      } catch {} // fall through to case with no tolerances
+   }
+   // either no tolerances or no matching signature for indistinguishable
+   return exactChecker
+})
+
+// now that we have `equal` and `exceeds`, pretty much everything else should
+// be easy:
+
+export const compare = onType([Any, Any], (math, [T, U]) => {
+   const eq = math.equal.resolve([T, U])
+   const gt = math.exceeds.resolve([T, U])
+   const zero = math.zero(T) // asymmetry here is unfortunate, but we have
+   // to pick some argument's zero to use, so the first argument seemed
+   // the most reasonable.
+   const one = math.one(T)
+   const negOne = math.negate(one)
+   if (math.typeOf(negOne) !== T) {
+      throw new TypeError(
+         `Cannot 'compare()' type '${T}' that has no negative one.`)
+   }
+   const hasnanT = math.hasnan(T)
+   const hasnanU = math.hasnan(U)
+   if (!hasnanT && !hasnanU) {
+      return Returns(T, (t, u) => eq(t, u) ? zero : gt(t, u) ? one : negOne)
+   }
+   if (hasnanU && !hasnanT) {
+      throw new TypeError(
+         `can't compare type ${T} without NaN and type ${U} with NaN`)
+   }
+   const isTnan = hasnanT && math.isnan.resolve([T])
+   const isUnan = hasnanU && math.isnan.resolve([U])
+   const nanT = hasnanT && math.nan(T)
+   return Returns(T, (t, u) => {
+      if (hasnanT && isTnan(t)) return nanT
+      if (hasnanU && isUnan(u)) return nanT // not a typo, stay in T
+      if (eq(t, u)) return zero
+      return gt(t, u) ? one : negOne
+   })
+})
+
+export const sign = onType(Any, (math, T) => {
+   const zero = math.zero(T)
+   const comp = math.compare.resolve([T, T])
+   return ReturnsAs(comp, t => comp(t, zero))
+})
+
+export const unequal = (math, types) => {
+   const eq = math.equal.resolve(types)
+   return ReturnsAs(eq, (...args) => !eq(...args))
+}
+
+export const larger = onType([Any, Any], (math, [T, U]) => {
+   const eq = math.equal.resolve([T, U])
+   const bigger = math.exceeds.resolve([T, U])
+   return boolnum((t, u) => !eq(t, u) && bigger(t, u))(math)
+})
+
+export const largerEq = onType([Any, Any], (math, [T, U]) => {
+   const eq = math.equal.resolve([T, U])
+   const bigger = math.exceeds.resolve([T, U])
+   return ReturnsAs(bigger, (t, u) => eq(t, u) || bigger(t, u))
+})
+
+export const smaller = onType([Any, Any], (math, [T, U]) => {
+   const eq = math.equal.resolve([T, U])
+   const bigger = math.exceeds.resolve([U, T])
+   return boolnum((t, u) => !eq(t, u) && bigger(u, t))(math)
+})
+
+export const smallerEq = onType([Any, Any], (math, [T, U]) => {
+   const eq = math.equal.resolve([T, U])
+   const bigger = math.exceeds.resolve([U, T])
+   return ReturnsAs(bigger, (t, u) => eq(t, u) || bigger(u, t))
+})

src/generic/utils.js

@@ -0,0 +1,13 @@
+import {ReturnsAs} from './helpers.js'
+import {onType, ResolutionError} from '#core/helpers.js'
+import {Returns} from '#core/Type.js'
+import {Any} from "#core/TypePatterns.js"
+
+export const isZero = (math, [T]) => {
+   if (!T) { // called with no arguments
+      throw new ResolutionError('isZero() requires one argument')
+   }
+   const z = math.zero(T)
+   const eq = math.equal.resolve([T, T])
+   return ReturnsAs(eq, x => eq(z, x))
+}