Fraction numerator denominator helpers

AUTHORS

@@ -280,6 +280,7 @@ Ikem Peter <ikempeter2020@gmail.com>
 Josh Kelley <joshkel@gmail.com>
 Richard Taylor <richard.taylor@claconnect.com>
 NilsDietrich <61544566+NilsDietrich@users.noreply.github.com>
+Chibuike Anselm <chibuikeanselm@Chibuikes-MacBook-Pro.local>
 anslem chibuike <144047596+AnslemHack@users.noreply.github.com>
 Ayomide Bamigbade <iamtryve@gmail.com>
 

src/expression/embeddedDocs/embeddedDocs.js

@@ -88,6 +88,8 @@ import { subtractDocs } from './function/arithmetic/subtract.js'
 import { unaryMinusDocs } from './function/arithmetic/unaryMinus.js'
 import { unaryPlusDocs } from './function/arithmetic/unaryPlus.js'
 import { xgcdDocs } from './function/arithmetic/xgcd.js'
+import { numDocs } from './function/fraction/num.js'
+import { denDocs } from './function/fraction/den.js'
 import { bitAndDocs } from './function/bitwise/bitAnd.js'
 import { bitNotDocs } from './function/bitwise/bitNot.js'
 import { bitOrDocs } from './function/bitwise/bitOr.js'
@@ -408,6 +410,8 @@ export const embeddedDocs = {
   unaryPlus: unaryPlusDocs,
   xgcd: xgcdDocs,
   invmod: invmodDocs,
+  num: numDocs,
+  den: denDocs,
 
   // functions - bitwise
   bitAnd: bitAndDocs,

src/expression/embeddedDocs/function/fraction/den.js

@@ -0,0 +1,8 @@
+export const denDocs = {
+  name: 'den',
+  category: 'Fraction',
+  syntax: ['den(x)'],
+  description: 'Get the denominator of a fraction.',
+  examples: ['den(fraction(2, 3))', 'den(fraction(5, 8))'],
+  seealso: ['num', 'fraction']
+}

src/expression/embeddedDocs/function/fraction/num.js

@@ -0,0 +1,8 @@
+export const numDocs = {
+  name: 'num',
+  category: 'Fraction',
+  syntax: ['num(x)'],
+  description: 'Get the numerator of a fraction.',
+  examples: ['num(fraction(2, 3))', 'num(fraction(5, 8))'],
+  seealso: ['den', 'fraction']
+}

src/factoriesAny.js

@@ -371,3 +371,5 @@ export { createOrTransform } from './expression/transform/or.transform.js'
 export { createNullishTransform } from './expression/transform/nullish.transform.js'
 export { createBitAndTransform } from './expression/transform/bitAnd.transform.js'
 export { createBitOrTransform } from './expression/transform/bitOr.transform.js'
+export { createNum } from './function/fraction/num.js'
+export { createDen } from './function/fraction/den.js'

src/function/fraction/den.js

@@ -0,0 +1,48 @@
+import { factory } from '../../utils/factory.js'
+import { deepMap } from '../../utils/collection.js'
+
+const name = 'den'
+const dependencies = ['typed', 'fraction']
+
+export const createDen = /* #__PURE__ */ factory(
+  name,
+  dependencies,
+  ({ typed, fraction }) => {
+    /**
+     * Get the denominator of a fraction.
+     * For a fraction `a/b`, the function returns `b`.
+     *
+     * For negative fractions like `-a/b` or `a/-b`, the denominator is
+     * always returned as a positive bigint. The sign is stored in the
+     * numerator. So `den(fraction(-2, 3))` and `den(fraction(2, -3))`
+     * both return `3n`.
+     *
+     * For matrices, the function is evaluated element wise.
+     *
+     * Syntax:
+     *
+     *    math.den(x)
+     *
+     * Examples:
+     *
+     *    math.den(math.fraction(2, 3))   // returns 3n
+     *    math.den(math.fraction('5/8'))  // returns 8n
+     *    math.den(math.fraction(-2, 3))  // returns 3n
+     *    math.den(math.fraction(2, -3))  // returns 3n
+     *    math.den(math.bignumber('0.5'))  // returns 2n
+     *
+     * See also:
+     *
+     *    num, fraction
+     *
+     * @param {Fraction | BigNumber | Array | Matrix} x
+     *            A fraction, BigNumber, or array with fractions
+     * @return {bigint | Array | Matrix} The denominator of x
+     */
+    return typed(name, {
+      Fraction: (x) => x.d,
+      BigNumber: (x) => fraction(x).d,
+      'Array | Matrix': typed.referToSelf((self) => (x) => deepMap(x, self))
+    })
+  }
+)

src/function/fraction/num.js

@@ -0,0 +1,50 @@
+import { factory } from '../../utils/factory.js'
+import { deepMap } from '../../utils/collection.js'
+
+const name = 'num'
+const dependencies = ['typed', 'fraction']
+
+export const createNum = /* #__PURE__ */ factory(
+  name,
+  dependencies,
+  ({ typed, fraction }) => {
+    /**
+     * Get the numerator of a fraction.
+     * For a fraction `a/b`, the function returns `a`.
+     *
+     * For negative fractions like `-a/b` or `a/-b`, the sign is always
+     * included in the numerator. Both forms are normalized internally, so
+     * `num(fraction(-2, 3))` and `num(fraction(2, -3))` both return `-2`.
+     *
+     * For matrices, the function is evaluated element wise.
+     *
+     * Syntax:
+     *
+     *    math.num(x)
+     *
+     * Examples:
+     *
+     *    math.num(math.fraction(2, 3))   // returns 2n
+     *    math.num(math.fraction('5/8'))  // returns 5n
+     *    math.num(math.fraction(-2, 3))  // returns -2n
+     *    math.num(math.fraction(2, -3))  // returns -2n
+     *    math.num(math.bignumber('0.5'))  // returns 1n
+     *
+     * See also:
+     *
+     *    den, fraction
+     *
+     * @param {Fraction | BigNumber | Array | Matrix} x
+     *            A fraction, BigNumber, or array with fractions
+     * @return {bigint | Array | Matrix} The numerator of x
+     */
+    return typed(name, {
+      Fraction: (x) => x.s * x.n,
+      BigNumber: (x) => {
+        const f = fraction(x)
+        return f.s * f.n
+      },
+      'Array | Matrix': typed.referToSelf((self) => (x) => deepMap(x, self))
+    })
+  }
+)

test/typescript-tests/testTypes.ts

@@ -3181,3 +3181,63 @@ Match types of exact positional arguments.
   expectTypeOf(mixArray3).toMatchTypeOf<MathArray<MathScalarType>>()
   expectTypeOf(unitArray3).toMatchTypeOf<MathArray<Unit>>()
 }
+
+/*
+Numerator and Denominator examples
+*/
+{
+  const math = create(all, {})
+
+  // Basic fraction tests
+  assert.strictEqual(math.num(math.fraction(2, 3)), BigInt(2))
+  assert.strictEqual(math.num(math.fraction(5, 8)), BigInt(5))
+  assert.strictEqual(math.den(math.fraction(2, 3)), BigInt(3))
+  assert.strictEqual(math.den(math.fraction(5, 8)), BigInt(8))
+  // BigNumber tests
+  assert.strictEqual(math.num(math.bignumber('0.5')), BigInt(1))
+  assert.strictEqual(math.den(math.bignumber('0.5')), BigInt(2))
+  assert.strictEqual(math.num(math.bignumber('1.5')), BigInt(3))
+  assert.strictEqual(math.den(math.bignumber('1.5')), BigInt(2))
+  expectTypeOf(math.num(math.bignumber('0.5'))).toMatchTypeOf<bigint>()
+  expectTypeOf(math.den(math.bignumber('0.5'))).toMatchTypeOf<bigint>()
+
+  // Negative fractions - sign is always in numerator
+  assert.strictEqual(math.num(math.fraction(-2, 3)), BigInt(-2))
+  assert.strictEqual(math.num(math.fraction(2, -3)), BigInt(-2))
+  assert.strictEqual(math.den(math.fraction(-2, 3)), BigInt(3))
+  assert.strictEqual(math.den(math.fraction(2, -3)), BigInt(3))
+
+  // Type checks
+  expectTypeOf(math.num(math.fraction(2, 3))).toMatchTypeOf<bigint>()
+  expectTypeOf(math.den(math.fraction(2, 3))).toMatchTypeOf<bigint>()
+
+  // Array of fractions
+  const fractionArray = [math.fraction(1, 2), math.fraction(3, 4)]
+  expectTypeOf(math.num(fractionArray)).toMatchTypeOf<MathArray>()
+  expectTypeOf(math.den(fractionArray)).toMatchTypeOf<MathArray>()
+  assert.deepStrictEqual(math.num(fractionArray), [BigInt(1), BigInt(3)])
+  assert.deepStrictEqual(math.den(fractionArray), [BigInt(2), BigInt(4)])
+
+  // Matrix of fractions
+  const fractionMatrix = math.matrix([math.fraction(1, 2), math.fraction(3, 4)])
+  expectTypeOf(math.num(fractionMatrix)).toMatchTypeOf<Matrix>()
+  expectTypeOf(math.den(fractionMatrix)).toMatchTypeOf<Matrix>()
+  assert.deepStrictEqual(
+    math.num(fractionMatrix),
+    math.matrix([BigInt(1), BigInt(3)])
+  )
+  assert.deepStrictEqual(
+    math.den(fractionMatrix),
+    math.matrix([BigInt(2), BigInt(4)])
+  )
+
+  // Chaining
+  expectTypeOf(
+    math.chain(math.fraction(2, 3)).num().done()
+  ).toMatchTypeOf<bigint>()
+  expectTypeOf(
+    math.chain(math.fraction(2, 3)).den().done()
+  ).toMatchTypeOf<bigint>()
+  assert.strictEqual(math.chain(math.fraction(2, 3)).num().done(), BigInt(2))
+  assert.strictEqual(math.chain(math.fraction(2, 3)).den().done(), BigInt(3))
+}

test/unit-tests/function/fraction/den.test.js

@@ -0,0 +1,72 @@
+import assert from 'assert'
+import math from '../../../../src/defaultInstance.js'
+
+describe('den', function () {
+  it('should return the denominator of a fraction', function () {
+    assert.strictEqual(math.den(math.fraction(2, 3)), 3n)
+    assert.strictEqual(math.den(math.fraction(4, 8)), 2n) // simplified to 1/2n
+    assert.strictEqual(math.den(math.fraction(5, 1)), 1n)
+  })
+
+  it('should return the denominator of a negative fraction', function () {
+    assert.strictEqual(math.den(math.fraction(-2, 3)), 3n)
+    assert.strictEqual(math.den(math.fraction(2, -3)), 3n)
+    assert.strictEqual(math.den(math.fraction(-2, -3)), 3n)
+  })
+
+  it('should return the denominator of a fraction string', function () {
+    assert.strictEqual(math.den(math.fraction('2/3')), 3n)
+    assert.strictEqual(math.den(math.fraction('5/8')), 8n)
+    assert.strictEqual(math.den(math.fraction('-5/8')), 8n)
+  })
+
+  it('should return the denominator for each element in a matrix', function () {
+    assert.deepStrictEqual(
+      math.den([math.fraction('2/3'), math.fraction('5/8')]),
+      [3n, 8n]
+    )
+    assert.deepStrictEqual(
+      math
+        .den(math.matrix([math.fraction('2/3'), math.fraction('5/8')]))
+        .valueOf(),
+      [3n, 8n]
+    )
+  })
+
+  it('should return the denominator of a BigNumber by converting to fraction', function () {
+    assert.strictEqual(math.den(math.bignumber('1')), 1n)
+    assert.strictEqual(math.den(math.bignumber('0.5')), 2n) // 0.5 = 1/2
+    assert.strictEqual(math.den(math.bignumber('0.25')), 4n) // 0.25 = 1/4
+    assert.strictEqual(math.den(math.bignumber('0.125')), 8n) // 0.125 = 1/8
+    assert.strictEqual(math.den(math.bignumber('-0.5')), 2n) // -0.5 = -1/2
+    assert.strictEqual(math.den(math.bignumber('0.75')), 4n) // 0.75 = 3/4
+    assert.strictEqual(math.den(math.bignumber('0.2')), 5n) // 0.2 = 1/5
+    assert.strictEqual(math.den(math.bignumber('-0.2')), 5n) // -0.2 = -1/5
+  })
+
+  it('should throw an error when called with an unsupported type of argument', function () {
+    assert.throws(function () {
+      math.den(new Date())
+    }, /TypeError: Unexpected type of argument/)
+    assert.throws(function () {
+      math.den(math.complex(2, 3))
+    }, /TypeError: Unexpected type of argument/)
+  })
+
+  it('should throw an error in case of invalid number of arguments', function () {
+    assert.throws(function () {
+      math.den()
+    }, /TypeError: Too few arguments/)
+    assert.throws(function () {
+      math.den(math.fraction(1, 2), 2)
+    }, /TypeError: Too many arguments/)
+  })
+
+  it('should LaTeX denominator', function () {
+    const expression = math.parse('den(fraction(1,2))')
+    assert.strictEqual(
+      expression.toTex(),
+      '\\mathrm{den}\\left(\\frac{1}{2}\\right)'
+    )
+  })
+})

test/unit-tests/function/fraction/num.test.js

@@ -0,0 +1,72 @@
+import assert from 'assert'
+import math from '../../../../src/defaultInstance.js'
+
+describe('num', function () {
+  it('should return the numerator of a fraction', function () {
+    assert.strictEqual(math.num(math.fraction(2, 3)), 2n)
+    assert.strictEqual(math.num(math.fraction(4, 8)), 1n) // simplified to 1/2
+    assert.strictEqual(math.num(math.fraction(5, 1)), 5n)
+  })
+
+  it('should return the numerator of a negative fraction', function () {
+    assert.strictEqual(math.num(math.fraction(-2, 3)), -2n)
+    assert.strictEqual(math.num(math.fraction(2, -3)), -2n)
+    assert.strictEqual(math.num(math.fraction(-2, -3)), 2n)
+  })
+
+  it('should return the numerator of a fraction string', function () {
+    assert.strictEqual(math.num(math.fraction('2/3')), 2n)
+    assert.strictEqual(math.num(math.fraction('5/8')), 5n)
+    assert.strictEqual(math.num(math.fraction('-5/8')), -5n)
+  })
+
+  it('should return the numerator for each element in a matrix', function () {
+    assert.deepStrictEqual(
+      math.num([math.fraction('2/3'), math.fraction('5/8')]),
+      [2n, 5n]
+    )
+    assert.deepStrictEqual(
+      math
+        .num(math.matrix([math.fraction('2/3'), math.fraction('5/8')]))
+        .valueOf(),
+      [2n, 5n]
+    )
+  })
+
+  it('should return the numerator of a BigNumber by converting to fraction', function () {
+    assert.strictEqual(math.num(math.bignumber('1')), 1n)
+    assert.strictEqual(math.num(math.bignumber('0.5')), 1n) // 0.5 = 1/2
+    assert.strictEqual(math.num(math.bignumber('0.25')), 1n) // 0.25 = 1/4
+    assert.strictEqual(math.num(math.bignumber('0.125')), 1n) // 0.125 = 1/8
+    assert.strictEqual(math.num(math.bignumber('-0.5')), -1n) // -0.5 = -1/2
+    assert.strictEqual(math.num(math.bignumber('0.75')), 3n) // 0.75 = 3/4
+    assert.strictEqual(math.num(math.bignumber('0.2')), 1n) // 0.2 = 1/5
+    assert.strictEqual(math.num(math.bignumber('-0.2')), -1n) // -0.2 = -1/5
+  })
+
+  it('should throw an error when called with an unsupported type of argument', function () {
+    assert.throws(function () {
+      math.num(new Date())
+    }, /TypeError: Unexpected type of argument/)
+    assert.throws(function () {
+      math.num(math.complex(2, 3))
+    }, /TypeError: Unexpected type of argument/)
+  })
+
+  it('should throw an error in case of invalid number of arguments', function () {
+    assert.throws(function () {
+      math.num()
+    }, /TypeError: Too few arguments/)
+    assert.throws(function () {
+      math.num(math.fraction(1, 2), 2)
+    }, /TypeError: Too many arguments/)
+  })
+
+  it('should LaTeX num', function () {
+    const expression = math.parse('num(fraction(1,2))')
+    assert.strictEqual(
+      expression.toTex(),
+      '\\mathrm{num}\\left(\\frac{1}{2}\\right)'
+    )
+  })
+})