# Math
Numeric stdlib functions are split by frequency of use, not by domain:
everyday operations stay bare top-level verbs, while specialised ones live
under the `math/` namespace. The split mirrors Python's builtins-vs-`math`
division and keeps top-level namespace uncluttered. All of these are
compiled into every runtime and need no import; see [Syntax and
Style](../01-Language/syntax-and-style) for the naming rationale.
## Functions
### Bare (everyday)
| Function | Purpose |
|---|---|
| `abs n` | Absolute value |
| `floor n`, `ceil n`, `round n` | Round down, up, or to nearest integer |
| `min a b ...`, `max a b ...` | Minimum / maximum of the arguments, or of a single list |
| `clamp n lo hi` | Clamp to the range `[lo, hi]` |
| `random` | Random float in `[0.0, 1.0)` |
| `mod a b` | Remainder of `a / b` (truncated division; sign follows the dividend) |
| `int x` | Coerce to integer, truncating toward zero; `nil` when a string cannot be parsed |
`random` takes no arguments: `[random]` returns a float in `[0.0, 1.0)`.
Scale it yourself for other ranges, or use `math/random-range` for a
float in a given interval.
### `math/` (specialised)
| Function | Purpose |
|---|---|
| `math/sqrt n` | Square root |
| `math/pow base exp` | `base` raised to `exp` |
| `math/sum n ...` / `math/sum $numbers` | Sum of all arguments or one list; `0` when empty |
| `math/avg n ...` / `math/avg $numbers` | Arithmetic mean; `0` when empty |
| `math/sin x`, `math/cos x`, `math/tan x` | Trigonometric functions (radians) |
| `math/asin x`, `math/acos x`, `math/atan x` | Inverse trigonometric functions (radians) |
| `math/atan2 y x` | Two-argument arc tangent, quadrant-aware |
| `math/exp x` | Euler's number raised to `x` |
| `math/ln x`, `math/log10 x`, `math/log2 x` | Natural, base-10, and base-2 logarithms |
| `math/sign x` | `-1`, `0`, or `1` by sign |
| `math/trunc x` | Truncate toward zero |
| `math/hypot x y` | `sqrt(x*x + y*y)`, computed without undue overflow or underflow |
| `math/lerp a b t` | Linear interpolation: `a + (b - a) * t` |
| `math/random-range min max` | Random float in `[min, max)` |
| `math/pi` | π — a zero-argument function, call `[math/pi]` |
| `math/euler` | Euler's number e — a zero-argument function, call `[math/euler]` |
`math/pi` and `math/euler` are functions, not constants: write `[math/pi]`,
never `$math/pi` or a bare `math/pi` reference. Use them inside grouped
expressions like any other call: `([math/pi] * [math/pow $r 2])`.
## Examples
# Everyday ops stay bare set qty 3 set price 19.99 set total ($price * $qty) echo "rounded:" [round $total] # 60 echo "clamped:" [clamp $total 0 50] # 50 echo "remainder:" [mod 17 5] # 2 echo "parsed:" [int "42"] # 42 # Specialised ops live under math/ echo "sqrt:" [math/sqrt 9] # 3 echo "hypotenuse:" [math/hypot 3 4] # 5 echo "lerp:" [math/lerp 0 100 0.25] # 25 echo "ranged:" [math/random-range 10 20] set radius 2.5 set area ([math/pi] * [math/pow $radius 2]) echo "area:" [round $area] # 20