math.rational

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { addRational } from "./math_rational_add_rational.ts";  ← addRational, another function of this group · built into the same file, even by a slim install
import { divideRational } from "./math_rational_divide_rational.ts";  ← divideRational, another function of this group · built into the same file, even by a slim install
import { multiplyRational } from "./math_rational_multiply_rational.ts";  ← multiplyRational, another function of this group · built into the same file, even by a slim install
import { subtractRational } from "./math_rational_subtract_rational.ts";  ← subtractRational, another function of this group · built into the same file, even by a slim install
import { type Rational, type RationalOp } from "./math_rational_types.ts";

/**
 * Add, subtract, multiply or divide two fractions exactly.
 *
 * The result is always reduced with a positive denominator, so equal values
 * have equal fields.
 */
export function calculateRational(a: Rational, op: RationalOp, b: Rational): Rational {
  switch (op) {
    case "add":
      return addRational(a, b);
    case "subtract":
      return subtractRational(a, b);
    case "multiply":
      return multiplyRational(a, b);
    case "divide":
      return divideRational(a, b);
    default:
      throw new RangeError(`unknown operation "${op}"`);
  }
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { gcdWide } from "./math_gcd_lcm.ts";  ← from math.gcd-lcm ^1.0.0 · built alongside by fune
import { type Rational } from "./math_rational_types.ts";

const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);

/**
 * Reduce a wide fraction and bring it back into the exact number range. The
 * arithmetic works on bigint products, which may be past 2^53, and only the
 * reduced result has to fit.
 */
export function rationalFromWide(numerator: bigint, denominator: bigint): Rational {
  if (denominator === 0n) {
    throw new RangeError("denominator must not be zero");
  }
  const g = gcdWide(numerator, denominator);
  let n = numerator / g;
  let d = denominator / g;
  if (d < 0n) {
    n = -n;
    d = -d;
  }
  if (n > MAX_SAFE || n < -MAX_SAFE || d > MAX_SAFE) {
    throw new RangeError("rational overflow: the reduced result exceeds 2^53 - 1");
  }
  // Number(-0n) is 0, so a zero result never comes back as -0.
  return { numerator: Number(n), denominator: Number(d) };
}

/** Build a reduced fraction with a positive denominator. */
export function rational(numerator: number, denominator: number): Rational {
  if (!Number.isInteger(numerator) || !Number.isInteger(denominator)) {
    throw new TypeError("numerator and denominator must be integers");
  }
  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)) {
    throw new RangeError("rational overflow: numerator and denominator must be within 2^53 - 1");
  }
  return rationalFromWide(BigInt(numerator), BigInt(denominator));
}

/** A checked, reduced operand as wide integers, ready to multiply without overflow. */
export function rationalParts(r: Rational): [bigint, bigint] {
  const n = rational(r.numerator, r.denominator);
  return [BigInt(n.numerator), BigInt(n.denominator)];
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { rationalFromWide, rationalParts } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/** a + b, reduced. */
export function addRational(a: Rational, b: Rational): Rational {
  const [an, ad] = rationalParts(a);
  const [bn, bd] = rationalParts(b);
  return rationalFromWide(an * bd + bn * ad, ad * bd);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { rationalFromWide, rationalParts } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/** a - b, reduced. */
export function subtractRational(a: Rational, b: Rational): Rational {
  const [an, ad] = rationalParts(a);
  const [bn, bd] = rationalParts(b);
  return rationalFromWide(an * bd - bn * ad, ad * bd);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { rationalFromWide, rationalParts } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/** a × b, reduced. */
export function multiplyRational(a: Rational, b: Rational): Rational {
  const [an, ad] = rationalParts(a);
  const [bn, bd] = rationalParts(b);
  return rationalFromWide(an * bn, ad * bd);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { rationalFromWide, rationalParts } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/** a ÷ b, reduced. Dividing by zero is an error, never an infinity. */
export function divideRational(a: Rational, b: Rational): Rational {
  const [an, ad] = rationalParts(a);
  const [bn, bd] = rationalParts(b);
  if (bn === 0n) {
    throw new RangeError("division by zero");
  }
  return rationalFromWide(an * bd, ad * bn);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { rationalParts } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/** -1, 0 or 1. Exact: cross-multiplied wide, never through a float. */
export function compareRational(a: Rational, b: Rational): number {
  const [an, ad] = rationalParts(a);
  const [bn, bd] = rationalParts(b);
  const left = an * bd;
  const right = bn * ad;
  return left < right ? -1 : left > right ? 1 : 0;
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { type RoundingMode, roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { rational } from "./math_rational_rational.ts";  ← rational, another function of this group · built into the same file, even by a slim install
import { type Rational } from "./math_rational_types.ts";

/**
 * The integer a fraction rounds to, under an explicit rounding mode: the
 * point where an exact rate becomes minor units, so the policy is the
 * caller's to state.
 */
export function rationalToInteger(r: Rational, mode: RoundingMode): number {
  const n = rational(r.numerator, r.denominator);
  return roundDiv(n.numerator, n.denominator, mode);
}