Core math | Moth

@core/math gives you Float constants and helper functions for common math operations. Bind it explicitly when you need trigonometry, rounding or clamping.

Binding

Bind the symbols you need with a direct-selection clause.

@core/math PI, sin, clamp

wave = sin(PI / 2.0)
bounded = clamp(wave, 0.0, 1.0)

io.line([:bounded=[bounded]])

You can also bind the whole namespace and access members through field access.

@core/math

angle = math.PI / 2.0
result = math.sin(angle)

Constants

PI, TAU and E form compile-time Float values. Use them directly in expressions.

Common functions

sin, cos, tan for trigonometry
atan2(y, x) for arc tangent of two values
sqrt, pow, log for powers and logarithms
abs, floor, ceil, round, trunc for rounding
min(a, b), max(a, b), clamp(x, min, max) for comparisons

All functions take Float values and return Float. For the full function list, backend behaviour and deferred surfaces, see Core math advanced.

@core/math provides Float constants and helper functions. It belongs to the binding-backed Core package family with no prelude alias, so it requires an explicit dependency clause.

@core/math carries Core origin with ExternalBinding backing. See Package origins and backing for origin and backing rules.

Dependency bindings

Bind individual symbols or the whole namespace:

@core/math PI, sin, clamp

@core/math

angle = math.PI / 2.0
result = math.sin(angle)

A namespace alias creates a file-local name:

@core/math as math

Constants

Constant	Type	Value
`PI`	`Float`	pi
`TAU`	`Float`	2 * pi
`E`	`Float`	Euler's number

Constants form compile-time Float values. They fold into expressions at compile time and do not produce runtime lookups.

Functions

All functions take Float parameters and return Float. Parameters stay positional-only. Named arguments lack support because binding-backed packages do not expose source-function features.

Function	Parameters	Returns
`sin(x)`	`Float`	`Float`
`cos(x)`	`Float`	`Float`
`tan(x)`	`Float`	`Float`
`atan2(y, x)`	`Float, Float`	`Float`
`log(x)`	`Float`	`Float`
`log2(x)`	`Float`	`Float`
`log10(x)`	`Float`	`Float`
`exp(x)`	`Float`	`Float`
`pow(base, exponent)`	`Float, Float`	`Float`
`sqrt(x)`	`Float`	`Float`
`abs(x)`	`Float`	`Float`
`floor(x)`	`Float`	`Float`
`ceil(x)`	`Float`	`Float`
`round(x)`	`Float`	`Float`
`trunc(x)`	`Float`	`Float`
`min(a, b)`	`Float, Float`	`Float`
`max(a, b)`	`Float, Float`	`Float`
`clamp(x, min, max)`	`Float, Float, Float`	`Float`

All functions keep infallible Moth signatures. A non-finite result still fails at the shared external Float boundary before ordinary Moth code observes it. The enclosing numeric failure mode decides what happens next: a function with builtin Error! recovers through that error channel, while a non-fallible function, a custom fallible channel or entry-selected root runtime code traps. NaN, positive infinity and negative infinity never become valid Moth Float values.

Access and return contracts

All parameters use shared access. No function requires mutable access. Every function returns a fresh Float value.

Backend behaviour

HTML-JS lowers each function to a JavaScript Math expression. clamp lowers to Math.min(Math.max(x, min), max). Constants fold into the expression at compile time.

HTML-Wasm lacks a Wasm lowering for these functions. See progress matrix for current target availability.

Unsupported source forms

Direct symbol-path clauses such as @core/math/sin face rejection. Use direct selections or a namespace clause.
Named arguments lack support. Binding-backed calls stay positional-only.
The package does not expose receiver methods, opaque types or Error! channels.

Deferred surfaces

Deferred math surfaces include integer math helpers, checked overflow modes, broader numeric tower support and non-JS lowerings. See progress matrix for current status.

Related concepts

For package origin and backing see Package origins and backing.
For dependency-path rules see Dependency paths.
For Float language semantics see Numbers.