math.integer-sqrt

Exact integer square root: the largest whole number whose square does not exceed n.

1.0.0 · published 2026-10-03 by charlie · Anterra

Pinned by 11 tests, run in TypeScript, Python and Rust.

What it does

The integer square root of `n`: the largest whole number `r` with `r * r <= n`, so `integerSqrt(24)` is 4 and `integerSqrt(25)` is 5.

It exists so that capabilities which need a square root of a whole number (economic order quantity, grid layouts) get the same answer in every language without going through floating point. `Math.floor(Math.sqrt(n))` is right for small numbers, but the double nearest to `n` is not `n` above 2^53 and the square root of a number just below a perfect square can round up to it, so each language here corrects the floating-point guess with exact integer arithmetic (TypeScript `bigint`, Python `math.isqrt`, Rust `i128`).

For example

integer_sqrt(0) → 0 zero
integer_sqrt(1) → 1 one
integer_sqrt(2) → 1 two truncates to one

The function

The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.

def integer_sqrt(n: int) -> int

n	int	a whole number from 0 to 2^53 - 1
returns	int	floor(sqrt(n)), exactly

Your code names it in one line, in the file that uses it

from fune.math.integer_sqrt import integer_sqrt  # math.integer-sqrt@^1

impl/python.py · 14 lines · open · raw

import math

MAX_SAFE = 2**53 - 1


def integer_sqrt(n: int) -> int:
    """The largest whole number whose square does not exceed ``n``.

    ``math.isqrt`` is exact; the range check keeps the answers the same as the
    TypeScript and Rust ports, which are limited to 2^53 - 1.
    """
    if isinstance(n, bool) or not isinstance(n, int) or n < 0 or n > MAX_SAFE:
        raise ValueError("n must be a whole number from 0 to 2^53 - 1, received %r" % (n,))
    return math.isqrt(n)

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.integer-sqrt

Download for Python math.integer-sqrt-1.0.0-python.fune · 3,920 bytes sha256 e26ba2f91cc4402cbbef5cd71ccb925b851eb6050f4eb526c739ab92fc5e274d

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

The whole function, every language, is one file too: math.integer-sqrt-1.0.0.fune, 5,586 bytes, sha256 7dc41dbf6a7e06cbd778a22b43f531a03b95d9e48c91f9ab7de1cbf549641f8c. It installs into a project of any language.

Customise it in your app

The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.

before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.

# fune: before math.integer-sqrt

after — your function gets the result and the arguments, and returns the final result.

# fune: after math.integer-sqrt

replace — it requires no other capability, so there is no dependency to replace.

step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show math.integer-sqrt --steps.

# fune: step math.integer-sqrt after <n|label>

Tests

A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.

Case	Arguments		Expected
zero	0	→	0
one	1	→	1
two truncates to one	2	→	1
just below a perfect square	24	→	4
a perfect square	25	→	5
just above a perfect square	26	→	5
a large perfect square, 94906265^2	9,007,199,136,250,225	→	94,906,265
one below a large perfect square: the double sqrt rounds up to 94906265, the answer is 94906264	9,007,199,136,250,224	→	94,906,264
the largest allowed input, 2^53 - 1	9,007,199,254,740,991	→	94,906,265
negative is an error	-1	→	error: n must be a whole number from 0 to 2^53 - 1

Show the other 1 test

Case	Arguments		Expected
a fraction is an error	2.5	→	error: n must be a whole number from 0 to 2^53 - 1

More from the author

Inputs are limited to 0 .. 2^53 - 1, the range where a JavaScript number is still an exact integer, so the three languages agree on every answer. A negative or fractional input, or one beyond that range, is an error.

To round a square root of a fraction `p / q` rather than truncate it, note that `floor(sqrt(p / q)) = integerSqrt(floor(p / q))`: the floor of a square root only changes at whole numbers. `inventory.eoq` uses this.

Files

Path	Bytes
README.md	1,110
impl/python.py	483
impl/rust.rs	970
impl/typescript.ts	612
vectors.json	960