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

integerSqrt(0) → 0 zero
integerSqrt(1) → 1 one
integerSqrt(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.

export function integerSqrt(n: number): number

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

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

impl/typescript.ts · 17 lines · open · raw

/**
 * The largest whole number whose square does not exceed `n`.
 *
 * The floating-point square root is only a first guess: it is corrected with
 * exact bigint arithmetic, so a number just below a perfect square never rounds
 * up to its root.
 */
export function integerSqrt(n: number): number {
  if (!Number.isSafeInteger(n) || n < 0) {
    throw new RangeError(`n must be a whole number from 0 to 2^53 - 1, received ${n}`);
  }
  const target = BigInt(n);
  let r = BigInt(Math.floor(Math.sqrt(n)));
  while (r * r > target) r -= 1n;
  while ((r + 1n) * (r + 1n) <= target) r += 1n;
  return Number(r);
}

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

Download for TypeScript math.integer-sqrt-1.0.0-typescript.fune · 4,052 bytes sha256 7bbe4d52a74acc583380c6d2da9ce62e0ab8b53f2e8090ba65a09b7d56645463

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

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