math.clamp

Clamp an integer to an inclusive range, refusing a range whose bounds are the wrong way round.

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

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

What it does

Returns `value` if it lies between `min` and `max` inclusive, otherwise the nearer bound.

A range with `min` greater than `max` is an error rather than a guess. The common one-liner `max(min, min(value, max))` quietly returns `min` for every input when the bounds are swapped, which hides the bug that swapped them.

For example

clamp(5, 0, 10) → 5 a value inside the range is returned unchanged
clamp(-3, 0, 10) → 0 below the range gives the lower bound
clamp(42, 0, 10) → 10 above the range gives the upper bound

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.

pub fn clamp(value: i64, min: i64, max: i64) -> i64

value	int
min	int	lowest value allowed, inclusive
max	int	highest value allowed, inclusive; must not be below min
returns	int

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

fune!(math.clamp@^1);  // then call clamp(…)

impl/rust.rs · 30 lines · open · raw

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

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one

/// Clamp `value` to the inclusive range `min..=max`.
///
/// Swapped bounds panic rather than answering `min` for everything, which is
/// what `value.max(min).min(max)` would quietly do.
///
/// # Panics
/// Panics if `min` is greater than `max`.
pub fn clamp(value: i64, min: i64, max: i64) -> i64 {
    if min > max {
        panic!("min must not be greater than max (min {}, max {})", min, max);
    }
    if value < min {
        min
    } else if value > max {
        max
    } else {
        value
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    // Refuse what the typed signature cannot hold, with the wording TypeScript
    // and Python use, rather than let the conversion below quietly change it.
    if (0..3).any(|i| matches!(args[i], Value::Float(f) if f.fract() != 0.0)) {
        panic!("clamp operates on integers only");
    }
    Value::Int(clamp(args[0].as_i64(), args[1].as_i64(), args[2].as_i64()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add math.clamp

Download for Rust math.clamp-1.0.0-rust.fune · 4,161 bytes sha256 60f9bbbb66405ad6ffaf1214b85887bc24d3d2bae67e94c236bfd621b971f22a

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

The whole function, every language, is one file too: math.clamp-1.0.0.fune, 5,509 bytes, sha256 2123f0c62d89da1b2ece2862eaf1514f0cbf2690d429dee046b20b51c896f2b4. 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.clamp

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

// fune: after math.clamp

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.clamp --steps.

// fune: step math.clamp 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
a value inside the range is returned unchanged	5, 0, 10	→	5
below the range gives the lower bound	-3, 0, 10	→	0
above the range gives the upper bound	42, 0, 10	→	10
exactly the lower bound is inside	0, 0, 10	→	0
exactly the upper bound is inside	10, 0, 10	→	10
a single-point range pins every value	99, 7, 7	→	7
a wholly negative range	-50, -20, -10	→	-20
a range across zero	3, -5, 5	→	3
a discount capped at 100 percent in basis points	12,500, 0, 10,000	→	10,000
the largest safe integers	9,007,199,254,740,991, -9,007,199,254,740,991, 9,007,199,254,740,990	→	9,007,199,254,740,990

Show the other 2 tests

Case	Arguments		Expected
swapped bounds are an error, not always the lower bound	5, 10, 0	→	error: min must not be greater than max
a fractional value is an error	2.5, 0, 10	→	error: integers only

More from the author

Integers only, so it is exact for amounts in minor units, basis points and counts. For money of one currency use `money.compare`, which checks the currencies as well.

Files

Path	Bytes
README.md	499
impl/python.py	657
impl/rust.rs	965
impl/typescript.ts	612
vectors.json	1,180