math.big-integer

export function calculateBigInteger(a: string, op: BigIntegerOp, b: string): string

export type BigIntegerOp = "add" | "subtract" | "multiply" | "divide" | "remainder" | "power";

import { calculateBigInteger } from "#fune/math.big-integer@^1";

import { type BigIntegerOp } from "./math_big_integer_types.ts";

const INTEGER = /^-?(0|[1-9][0-9]*)$/;

/** The largest result, in bits, that power will build: about 19,700 decimal digits. */
export const MAX_POWER_BITS = 65536;

/** Parse the registry's decimal integer form. "-0", "+1", "01" and " 1" are refused. */
export function parseBigInteger(text: string): bigint {
  if (typeof text !== "string" || !INTEGER.test(text) || text === "-0") {
    throw new RangeError(`not a whole number in decimal: "${text}"`);
  }
  return BigInt(text);
}

function bitLength(value: bigint): number {
  return value === 0n ? 0 : (value < 0n ? -value : value).toString(2).length;
}

/**
 * Raise to a power, refusing results beyond MAX_POWER_BITS before building
 * them, so a typo cannot hang the process on a million-digit number.
 */
export function powerBigInteger(base: bigint, exponent: bigint): bigint {
  if (exponent < 0n) {
    throw new RangeError("exponent must not be negative");
  }
  const magnitude = base < 0n ? -base : base;
  if (magnitude >= 2n && BigInt(bitLength(magnitude)) * exponent > BigInt(MAX_POWER_BITS)) {
    throw new RangeError(`result too large: power is limited to ${MAX_POWER_BITS} bits`);
  }
  if (magnitude <= 1n) {
    // 0^0 is 1, as in every language's integer power; (-1)^n alternates.
    if (exponent === 0n) return 1n;
    if (base === -1n) return exponent % 2n === 0n ? 1n : -1n;
    return base;
  }
  return base ** exponent;
}

/**
 * Exact integer arithmetic on decimal strings. Division truncates towards
 * zero and the remainder takes the sign of the dividend, as in TypeScript,
 * Rust, C and Java (Python floors, and is adjusted to agree).
 */
export function calculateBigInteger(a: string, op: BigIntegerOp, b: string): string {
  const x = parseBigInteger(a);
  const y = parseBigInteger(b);
  switch (op) {
    case "add":
      return (x + y).toString();
    case "subtract":
      return (x - y).toString();
    case "multiply":
      return (x * y).toString();
    case "divide":
      if (y === 0n) throw new RangeError("division by zero");
      return (x / y).toString();
    case "remainder":
      if (y === 0n) throw new RangeError("division by zero");
      return (x % y).toString();
    case "power":
      return powerBigInteger(x, y).toString();
    default:
      throw new RangeError(`unknown operation "${op}"`);
  }
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add math.big-integer

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./math.big-integer-1.0.0-typescript.fune, or fetch it from a terminal with fune pull math.big-integer@1.0.0:typescript.

The whole function, every language, is one file too: math.big-integer-1.0.0.fune, 27,178 bytes, sha256 242eb37623145ad5d7b0d7b9063ea4d93bac3ec93828ccab3e7149d5c7ed9af3. It installs into a project of any language.

// fune: before math.big-integer

// fune: after math.big-integer

// fune: step math.big-integer after <n|label>

More from the author

## Operations

- `add`, `subtract`, `multiply`: exact. - `divide`: the quotient truncated towards zero, so -7 / 2 is -3. - `remainder`: takes the sign of the dividend, so -7 rem 2 is -1 and a = (a / b) × b + (a rem b) always holds. This is TypeScript's and Rust's rule; Python floors by default and is adjusted to agree. - `power`: the exponent is 0 or more; 0^0 is 1.

## Limits

`power` refuses a result that would exceed 65,536 bits (about 19,700 decimal digits) before building it, estimated as bits(base) × exponent, the same way in every language, so a slip of the exponent fails at once instead of hanging. The other operations have no limit beyond memory and time; the Rust side is schoolbook multiplication and shift-subtract division, which is quadratic.

## Why a capability, and what it exports

TypeScript (`bigint`) and Python (`int`) have arbitrary-precision integers built in. Rust's standard library does not, and the registry takes no crates, so the Rust module is a real implementation: it exports a `BigInt` type (`from_i64`, `from_i128`, `add`, `sub`, `mul`, `div_rem`, `pow`, `to_i64`, `to_i128`, `div_rem_small`, ordering and `Display`) that other capabilities build on, plus `parse_big_integer` and `power_big_integer`. TypeScript and Python export `parseBigInteger` / `parse_big_integer` and `powerBigInteger` / `power_big_integer` over their native integers.

Numbers must be in canonical form: an optional "-", then digits with no leading zero. "-0", "+1", "01", " 1" and "1.0" are errors, not guesses.

Files