a/docs/math.md

math

a keeps Lua's standard math library intact and adds a handful of functions that come up constantly in everyday scripting: rounding, clamping, sign, finiteness, and linear rescaling. The additions live on the same global math table, so math.floor and math.round sit side by side.

print(math.round(3.14159, 2))   --> 3.14
print(math.clamp(120, 0, 100))  --> 100
print(math.scale(0.5, 0, 1, 0, 255)) --> 127.5

Everything here errors on a non-number argument rather than coercing it, so a stray nil or string surfaces at the call site instead of producing a silent NaN.

math.round(value [, places])

Round to the nearest integer, or to places decimal places. Rounding is half away from zero (so 0.5 → 1, -0.5 → -1), computed exactly — it does not suffer the floor(x + 0.5) error that mis-rounds values just under .5.

The return type depends on places:

• places omitted or 0 → an integer,
• places > 0 → a float rounded to that many decimals.

math.round(2.5)        --> 3       (integer)
math.round(-2.5)       --> -3
math.round(3.14159, 2) --> 3.14    (float)
math.round(7)          --> 7       (integers pass through)

places must be a non-negative integer. A non-finite value (NaN/infinity) or a result outside Lua's integer range is an error.

math.clamp(value, min, max)

Constrain value to the interval [min, max]. Either bound may be nil to leave that side open:

math.clamp(15, 0, 10)     --> 10
math.clamp(-3, 0, 10)     --> 0
math.clamp(5, 0, 10)      --> 5
math.clamp(-3, 0, nil)    --> 0    (no upper bound)
math.clamp(99, nil, 10)   --> 10   (no lower bound)

It is an error for min to exceed max.

math.isFinite(value)

Return true if value is a number that is neither NaN nor infinite. Anything that is not a number returns false (it does not error), making it a safe guard before arithmetic:

math.isFinite(1.5)       --> true
math.isFinite(1/0)       --> false  (infinity)
math.isFinite(0/0)       --> false  (NaN)
math.isFinite("x")       --> false

math.sign(value)

Return the sign of a number as -1, 0, or 1. Zero (and NaN) yield 0.

math.sign(-42)   --> -1
math.sign(0)     -->  0
math.sign(3.5)   -->  1

math.scale(value, inMin, inMax, outMin, outMax [, clamp])

Linearly remap value from the input range [inMin, inMax] onto the output range [outMin, outMax]. With clamp = true, the result is held within the output range for inputs that fall outside the input range.

-- map a 0–1023 ADC reading to a 0–100 percentage
math.scale(512, 0, 1023, 0, 100)          --> ~50.05

-- ranges may descend, and you can invert
math.scale(0, 0, 100, 100, 0)             --> 100

-- clamp keeps out-of-range inputs inside the output band
math.scale(2.0, 0, 1, 0, 255)             --> 510    (unclamped)
math.scale(2.0, 0, 1, 0, 255, true)       --> 255    (clamped)

The input range cannot be empty — inMin == inMax is an error (it would divide by zero).

Notes

• Additions, not replacements. All of stock Lua's math — floor, ceil, abs, min, max, sqrt, huge, pi, tointeger, type, … — is still there unchanged.
• round is the only type-changing one. It returns an integer for places == 0 and a float otherwise; the rest return whatever fits naturally.
• Aggregates over tables live in table. For the min/max/mean/sum of a collection, see table.min, table.max, table.mean, table.sum.