math.big-integer

def calculate_big_integer(a: str, op: BigIntegerOp, b: str) -> str

BigIntegerOp = Literal["add", "subtract", "multiply", "divide", "remainder", "power"]

from fune.math.big_integer import calculate_big_integer  # math.big-integer@^1

import re

from .math_big_integer_types import BigIntegerOp

_INTEGER = re.compile(r"^-?(0|[1-9][0-9]*)$")

#: The largest result, in bits, that power will build: about 19,700 decimal digits.
MAX_POWER_BITS = 65536


def parse_big_integer(text: str) -> int:
    """Parse the registry's decimal integer form. "-0", "+1", "01" and " 1" are refused."""
    if not isinstance(text, str) or not _INTEGER.fullmatch(text) or text == "-0":
        raise ValueError('not a whole number in decimal: "%s"' % (text,))
    return int(text)


def _trunc_div(x: int, y: int) -> int:
    q = abs(x) // abs(y)
    return -q if (x < 0) != (y < 0) else q


def power_big_integer(base: int, exponent: int) -> int:
    """Raise to a power, refusing results beyond MAX_POWER_BITS before building them."""
    if exponent < 0:
        raise ValueError("exponent must not be negative")
    magnitude = abs(base)
    if magnitude >= 2 and magnitude.bit_length() * exponent > MAX_POWER_BITS:
        raise ValueError("result too large: power is limited to %d bits" % (MAX_POWER_BITS,))
    if magnitude <= 1:
        if exponent == 0:
            return 1
        if base == -1:
            return 1 if exponent % 2 == 0 else -1
        return base
    return base ** exponent


def calculate_big_integer(a: str, op: BigIntegerOp, b: str) -> str:
    """Exact integer arithmetic on decimal strings.

    Division truncates towards zero and the remainder takes the sign of the
    dividend, as in TypeScript and Rust. Python's own // floors, so it is not
    used directly on signed values.
    """
    x = parse_big_integer(a)
    y = parse_big_integer(b)
    if op == "add":
        return str(x + y)
    if op == "subtract":
        return str(x - y)
    if op == "multiply":
        return str(x * y)
    if op == "divide":
        if y == 0:
            raise ZeroDivisionError("division by zero")
        return str(_trunc_div(x, y))
    if op == "remainder":
        if y == 0:
            raise ZeroDivisionError("division by zero")
        return str(x - y * _trunc_div(x, y))
    if op == "power":
        return str(power_big_integer(x, y))
    raise ValueError('unknown operation "%s"' % (op,))

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./math.big-integer-1.0.0-python.fune, or fetch it from a terminal with fune pull math.big-integer@1.0.0:python.

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