std/math module

The std/math module provides comprehensive mathematical functions including constants, arithmetic operations, trigonometry, logarithms, and random number generation.

Import

import "std/math";

Constants

pi

Returns the mathematical constant π (pi).

let value = math.pi();

return

float

The value of π (approximately 3.14159…)

e

Returns Euler’s number e.

let value = math.e();

return

float

The value of e (approximately 2.71828…)

tau

Returns τ (tau), equal to 2π.

let value = math.tau();

return

float

The value of τ (approximately 6.28318…)

inf

Returns positive infinity.

let value = math.inf();

return

float

Positive infinity

nan

Returns NaN (Not a Number).

let value = math.nan();

return

float

NaN value

Basic arithmetic

abs

Returns the absolute value of a number.

let result = math.abs(x);

int | float

required

Number to get absolute value of

return

int | float

Absolute value of x (same type as input)

Example:

import "std/math";

println(math.abs(-42));    // 42
println(math.abs(3.14));   // 3.14
println(math.abs(-7.5));   // 7.5

sign

Returns the sign of a number as -1, 0, or 1.

let result = math.sign(x);

int | float

required

Number to get the sign of

return

int

-1 if negative, 0 if zero, 1 if positive

Example:

import "std/math";

println(math.sign(-5));    // -1
println(math.sign(0));     // 0
println(math.sign(42));    // 1

min

Returns the smaller of two numbers.

let result = math.min(a, b);

int | float

required

First number

int | float

required

Second number

return

int | float

The smaller value

max

Returns the larger of two numbers.

let result = math.max(a, b);

int | float

required

First number

int | float

required

Second number

return

int | float

The larger value

clamp

Clamps a value to the range [lo, hi].

let result = math.clamp(x, lo, hi);

int | float

required

Value to clamp

int | float

required

Lower bound (must be ≤ hi)

int | float

required

Upper bound (must be ≥ lo)

return

int | float

Value clamped to [lo, hi]

Example:

import "std/math";

println(math.clamp(5, 0, 10));   // 5
println(math.clamp(-5, 0, 10));  // 0
println(math.clamp(15, 0, 10));  // 10

Rounding

floor

Rounds down to the nearest integer.

let result = math.floor(x);

float

required

Number to round down

return

float

Largest integer ≤ x

ceil

Rounds up to the nearest integer.

let result = math.ceil(x);

float

required

Number to round up

return

float

Smallest integer ≥ x

round

Rounds to the nearest integer.

let result = math.round(x);

float

required

Number to round

return

float

Nearest integer to x

trunc

Truncates the fractional part, returning just the integer portion.

let result = math.trunc(x);

float

required

Number to truncate

return

float

Integer portion of x

fract

Returns the fractional part of a number.

let result = math.fract(x);

float

required

Number to get fractional part of

return

float

Fractional portion of x (x - trunc(x))

Example:

import "std/math";

println(math.floor(3.7));   // 3.0
println(math.ceil(3.2));    // 4.0
println(math.round(3.5));   // 4.0
println(math.trunc(3.7));   // 3.0
println(math.fract(3.7));   // 0.7

Powers and roots

sqrt

Returns the square root of a number. The argument must be non-negative.

let result = math.sqrt(x);

float

required

Number to take square root of (must be ≥ 0)

return

float

Square root of x

cbrt

Returns the cube root of a number.

let result = math.cbrt(x);

float

required

Number to take cube root of

return

float

Cube root of x

pow

Raises x to the power of y.

let result = math.pow(x, y);

float

required

Base

float

required

Exponent

return

float

x raised to the power y

hypot

Returns the Euclidean norm: sqrt(x² + y²).

let result = math.hypot(x, y);

float

required

First component

float

required

Second component

return

float

Euclidean distance from origin

Example:

import "std/math";

println(math.sqrt(49));        // 7.0
println(math.cbrt(27));        // 3.0
println(math.pow(2, 10));      // 1024.0
println(math.hypot(3, 4));     // 5.0

Trigonometry

All trigonometric functions use radians. Use degrees() and radians() to convert.

sin

Returns the sine of an angle in radians.

let result = math.sin(x);

float

required

Angle in radians

return

float

Sine of x

cos

Returns the cosine of an angle in radians.

let result = math.cos(x);

float

required

Angle in radians

return

float

Cosine of x

tan

Returns the tangent of an angle in radians.

let result = math.tan(x);

float

required

Angle in radians

return

float

Tangent of x

asin

Returns the inverse sine (arcsine) of a value. The argument must be in [-1, 1].

let result = math.asin(x);

float

required

Value to take inverse sine of (must be in [-1, 1])

return

float

Angle in radians in the range [-π/2, π/2]

acos

Returns the inverse cosine (arccosine) of a value. The argument must be in [-1, 1].

let result = math.acos(x);

float

required

Value to take inverse cosine of (must be in [-1, 1])

return

float

Angle in radians in the range [0, π]

atan

Returns the inverse tangent (arctangent) of a value.

let result = math.atan(x);

float

required

Value to take inverse tangent of

return

float

Angle in radians in the range [-π/2, π/2]

atan2

Returns the quadrant-aware inverse tangent of y/x.

let result = math.atan2(y, x);

float

required

Y coordinate

float

required

X coordinate

return

float

Angle in radians in the range [-π, π]

Example:

import "std/math";

let angle = math.radians(45);
println(math.sin(angle));  // 0.7071...
println(math.cos(angle));  // 0.7071...
println(math.tan(angle));  // 1.0

Exponentials and logarithms

exp

Returns e raised to the power x.

let result = math.exp(x);

float

required

Exponent

return

float

e^x

ln

Returns the natural logarithm (base e) of x. Requires x > 0.

let result = math.ln(x);

float

required

Number to take natural log of (must be > 0)

return

float

Natural logarithm of x

log2

Returns the base-2 logarithm of x. Requires x > 0.

let result = math.log2(x);

float

required

Number to take log base 2 of (must be > 0)

return

float

Base-2 logarithm of x

log10

Returns the base-10 logarithm of x. Requires x > 0.

let result = math.log10(x);

float

required

Number to take log base 10 of (must be > 0)

return

float

Base-10 logarithm of x

log

Returns the logarithm of x in a custom base. Requires x > 0, base > 0, and base ≠ 1.

let result = math.log(x, base);

float

required

Number to take logarithm of (must be > 0)

base

float

required

Logarithm base (must be > 0 and ≠ 1)

return

float

Logarithm of x in the specified base

Example:

import "std/math";

println(math.exp(1));       // 2.71828... (e)
println(math.ln(math.e())); // 1.0
println(math.log2(1024));   // 10.0
println(math.log10(1000));  // 3.0
println(math.log(8, 2));    // 3.0

Interpolation and conversion

lerp

Linear interpolation between two values.

let result = math.lerp(a, b, t);

float

required

Start value

float

required

End value

float

required

Interpolation factor (0 = a, 1 = b)

return

float

Interpolated value: a + (b - a) * t

Example:

import "std/math";

println(math.lerp(10, 20, 0.0));   // 10.0
println(math.lerp(10, 20, 0.5));   // 15.0
println(math.lerp(10, 20, 1.0));   // 20.0
println(math.lerp(10, 20, 0.25));  // 12.5

degrees

Converts radians to degrees.

let result = math.degrees(r);

float

required

Angle in radians

return

float

Angle in degrees

radians

Converts degrees to radians.

let result = math.radians(d);

float

required

Angle in degrees

return

float

Angle in radians

Example:

import "std/math";

let rad = math.radians(180);
println(rad);  // 3.14159... (π)

let deg = math.degrees(math.pi());
println(deg);  // 180.0

Validation

is_finite

Returns true if the value is finite (not infinity or NaN).

let result = math.is_finite(x);

float

required

Value to check

return

bool

true if x is finite, false otherwise

is_nan

Returns true if the value is NaN (Not a Number).

let result = math.is_nan(x);

float

required

Value to check

return

bool

true if x is NaN, false otherwise

is_inf

Returns true if the value is infinite (positive or negative).

let result = math.is_inf(x);

float

required

Value to check

return

bool

true if x is infinite, false otherwise

Example:

import "std/math";

println(math.is_finite(42.0));      // true
println(math.is_finite(math.inf())); // false
println(math.is_nan(math.nan()));    // true
println(math.is_inf(math.inf()));    // true

Random number generation

seed

Seeds the random number generator for deterministic random sequences.

math.seed(n);

int

required

Seed value for the RNG

return

void

No return value

rand_float

Returns a random float in the range [0.0, 1.0).

let value = math.rand_float();

return

float

Random float in [0.0, 1.0)

rand_bool

Returns a random boolean value (50/50 chance).

let value = math.rand_bool();

return

bool

Random true or false

rand_int

Returns a random integer in the range [a, b] (inclusive on both ends).

let value = math.rand_int(a, b);

int

required

Minimum value (inclusive)

int

required

Maximum value (inclusive, must be ≥ a)

return

int

Random integer in [a, b]

rand_range

Returns a random float in the range [a, b).

let value = math.rand_range(a, b);

float

required

Minimum value (inclusive)

float

required

Maximum value (exclusive, must be > a)

return

float

Random float in [a, b)

Example:

import "std/math";

// Deterministic random with seed
math.seed(1337);
let id = math.rand_int(1000, 9999);
println(f"ID: {id}");

// Random operations
println(math.rand_bool());           // true or false
println(math.rand_float());          // 0.0 to 1.0
println(math.rand_int(1, 6));        // Dice roll: 1-6
println(math.rand_range(0.0, 100.0)); // 0.0 to 100.0

Usage patterns

Circle calculations

import "std/math";

let radius = 5.0;
let circumference = 2.0 * math.pi() * radius;
let area = math.pi() * math.pow(radius, 2);

println(f"Radius: {radius}");
println(f"Circumference: {circumference}");
println(f"Area: {area}");

Distance calculation

import "std/math";

let x1 = 0.0;
let y1 = 0.0;
let x2 = 3.0;
let y2 = 4.0;

let distance = math.hypot(x2 - x1, y2 - y1);
println(f"Distance: {distance}");  // 5.0

Random game mechanics

import "std/math";

math.seed(42);  // Reproducible gameplay

// Dice roll
let roll = math.rand_int(1, 6);
println(f"You rolled a {roll}");

// Random chance
if math.rand_bool() {
    println("Critical hit!");
}

// Damage with variance
let base_damage = 100;
let variance = math.rand_range(-10.0, 10.0);
let damage = base_damage + variance;
println(f"Damage: {damage}");

Angle calculations

import "std/math";

// Convert 45 degrees to radians
let angle_deg = 45.0;
let angle_rad = math.radians(angle_deg);

println(f"Sin(45°) = {math.sin(angle_rad)}");
println(f"Cos(45°) = {math.cos(angle_rad)}");

// Convert back
let back_to_degrees = math.degrees(angle_rad);
println(f"Back to degrees: {back_to_degrees}");

Get Started

Language Guide

Standard Library

Advanced Topics

CLI Reference

Development

​Import

​Constants

​pi

​e

​tau

​inf

​nan

​Basic arithmetic

​abs

​sign

​min

​max

​clamp

​Rounding

​floor

​ceil

​round

​trunc

​fract

​Powers and roots

​sqrt

​cbrt

​pow

​hypot

​Trigonometry

​sin

​cos

​tan

​asin

​acos

​atan

​atan2

​Exponentials and logarithms

​exp

​ln

​log2

​log10

​log

​Interpolation and conversion

​lerp

​degrees

​radians

​Validation

​is_finite

​is_nan

​is_inf

​Random number generation

​seed

​rand_float

​rand_bool

​rand_int

​rand_range

​Usage patterns

​Circle calculations

​Distance calculation

​Random game mechanics

​Angle calculations

Build docs developers (and LLMs) love

Import

Constants

pi

e

tau

inf

nan

Basic arithmetic

abs

sign

min

max

clamp

Rounding

floor

ceil

round

trunc

fract

Powers and roots

sqrt

cbrt

pow

hypot

Trigonometry

sin

cos

tan

asin

acos

atan

atan2

Exponentials and logarithms

exp

ln

log2

log10

log

Interpolation and conversion

lerp

degrees

radians

Validation

is_finite

is_nan

is_inf

Random number generation

seed

rand_float

rand_bool

rand_int

rand_range

Usage patterns

Circle calculations

Distance calculation

Random game mechanics

Angle calculations