Guide Manual Packages Playground

@std/math

API Reference

class Math

Static numeric helpers: constants, comparisons, rounding, and the runtime-backed transcendental functions. The class declares no init, so an instance holds nothing and reaches no method: call every member as Math.name(...).

Angles are radians. Convert degrees with value * Math.PI() / 180.0. The functions backed by the runtime (sqrt, sin, cos, tan, atan2, pow, floor, ceil, round, log) follow IEEE-754: a negative argument to sqrt or log gives NaN, log(0.0) gives -Infinity, and 0.0 raised to a negative power gives Infinity. print renders those as NaN, inf, and -inf.

abs, min, max, and clamp are written in Rasmalai and compare with < and >. A NaN loses every such comparison, so a NaN reaching min or max is dropped and the other argument comes back. Reach one with Math.sqrt(0.0 - 1.0).

Nothing in this class throws.

fn E(): Float

Base of the natural logarithm. log(Math.E()) is exactly 1.0.

returns — 2.718281828459045.

fn PI(): Float

Ratio of a circle's circumference to its diameter. Multiply by a degree count and divide by 180.0 to turn degrees into radians.

returns — 3.141592653589793.

import { Math } from "@std/math";

print(Math.PI());
Run in Playground
fn TAU(): Float

A full turn in radians: 2 * PI(). Hand a phase in [0.0, TAU()) to sin or cos rather than normalizing it yourself.

returns — 6.283185307179586.

fn abs(x: Float): Float

Absolute value.

x — input value.

returns — x when x is not less than 0.0, otherwise 0.0 - x. -0.0 and NaN are not less than 0.0, so they come back unchanged.

import { Math } from "@std/math";

print(Math.abs(0.0 - 3.5));
Run in Playground
fn atan2(y: Float, x: Float): Float

Four-quadrant arctangent: the angle of the vector (x, y).

y — vertical component.

x — horizontal component. The order is y first, x second.

returns — the angle in radians in [-PI, PI], measured counterclockwise from the positive x axis. atan2(0.0, 0.0) is 0.0, and atan2(0.0, -1.0) is Math.PI().

import { Math } from "@std/math";

print(Math.atan2(1.0, 1.0) * 180.0 / Math.PI());
Run in Playground
fn ceil(x: Float): Float

Smallest integer not less than x.

x — input value.

returns — ceil(x) as a Float, so 2.1 gives 3.0 and -2.7 gives -2.0.

import { Math } from "@std/math";

print(Math.ceil(2.1));
Run in Playground
fn clamp(v: Float, minVal: Float, maxVal: Float): Float

Clamp v into the inclusive range [minVal, maxVal].

v — value to clamp.

minVal — lower bound.

maxVal — upper bound.

returns — minVal when v < minVal, maxVal when v > maxVal, otherwise v. The two bounds are not checked against each other, and a NaN v comes back as NaN because both comparisons fail.

import { Math } from "@std/math";

print(Math.clamp(9.0, 0.0, 1.0));
Run in Playground
fn cos(x: Float): Float

Cosine of an angle in radians.

x — angle in radians; convert degrees with x * Math.PI() / 180.0.

returns — cos(x), in [-1.0, 1.0]. It is 1.0 at 0.0 and -1.0 at Math.PI().

import { Math } from "@std/math";

print(Math.cos(Math.PI()));
Run in Playground
fn floor(x: Float): Float

Largest integer not greater than x.

x — input value.

returns — floor(x) as a Float, so 2.7 gives 2.0 and -2.5 gives -3.0.

import { Math } from "@std/math";

print(Math.floor(0.0 - 2.5));
Run in Playground
fn log(x: Float): Float

Natural logarithm, computed by the runtime math intrinsic.

x — value to take the logarithm of.

returns — ln(x). log(1.0) is 0.0 and log(Math.E()) is 1.0. Per IEEE-754, log(0.0) is -Infinity and a negative x gives NaN.

import { Math } from "@std/math";

print(Math.log(Math.E()));
Run in Playground
fn max(a: Float, b: Float): Float

Larger of two values.

a — first candidate.

b — second candidate.

returns — a when a > b, otherwise b. Equal values give b, and a NaN in either slot loses the comparison, so the other argument comes back.

import { Math } from "@std/math";

print(Math.max(3.0, 7.0));
Run in Playground
fn min(a: Float, b: Float): Float

Smaller of two values.

a — first candidate.

b — second candidate.

returns — a when a < b, otherwise b. Equal values give b, and a NaN in either slot loses the comparison, so the other argument comes back.

import { Math } from "@std/math";

print(Math.min(3.0, 7.0));
Run in Playground
fn pow(base: Float, exp: Float): Float

Exponentiation, computed by the runtime math intrinsic.

base — value to raise.

exp — exponent.

returns — base raised to exp. pow(0.0, 0.0) is 1.0, a negative base with a fractional exponent gives NaN, and 0.0 raised to a negative power gives Infinity.

import { Math } from "@std/math";

print(Math.pow(2.0, 10.0));
Run in Playground
fn round(x: Float): Float

Nearest integer, returned as a Float.

x — input value.

returns — round(x). Ties go away from zero rather than to the nearest even number, so 2.5 gives 3.0, 0.5 gives 1.0, and -2.5 gives -3.0.

import { Math } from "@std/math";

print(Math.round(2.5));
print(Math.round(0.0 - 2.5));
Run in Playground
fn sin(x: Float): Float

Sine of an angle in radians.

x — angle in radians; convert degrees with x * Math.PI() / 180.0.

returns — sin(x), in [-1.0, 1.0].

import { Math } from "@std/math";

print(Math.sin(Math.PI() / 2.0));
Run in Playground
fn sqrt(x: Float): Float

Square root, computed by the runtime math intrinsic.

x — value to take the root of.

returns — sqrt(x) as a Float. A negative x yields NaN, which IEEE-754 requires rather than a thrown error.

import { Math } from "@std/math";

print(Math.sqrt(9.0));
Run in Playground
fn tan(x: Float): Float

Tangent of an angle in radians.

x — angle in radians; convert degrees with x * Math.PI() / 180.0.

returns — tan(x). The result is unbounded: it grows without limit as x approaches Math.PI() / 2.0 from either side.

import { Math } from "@std/math";

print(Math.round(Math.tan(Math.PI() / 4.0) * 1000.0) / 1000.0);
Run in Playground
class Vec2

2D float vector with dot products and lengths. The fields are public and mutable, so a Vec2 works as a plain record: nothing is normalized, no component is range-checked, and the type is meant for positions, offsets, and directions.

init(x: Float, y: Float)

fields

  • x: Float
  • y: Float
fn dot(other: Vec2): Float

Dot product of two 2D vectors: one length times the projection of the other onto it.

other — right-hand vector.

returns — this.x * other.x + this.y * other.y, which is 0.0 for two non-zero vectors that are perpendicular.

import { Vec2 } from "@std/math";

print(new Vec2(1.0, 2.0).dot(new Vec2(3.0, 4.0)));
Run in Playground
fn length(): Float

Euclidean length: the distance from the origin to this vector.

returns — Math.sqrt(this.lengthSq()).

import { Vec2 } from "@std/math";

let v = new Vec2(3.0, 4.0);
print(v.length());
Run in Playground
fn lengthSq(): Float

Squared length. Comparing squares skips the square root, so prefer this when you only need to know which of two vectors is longer or whether two distances are equal.

returns — this.dot(this), the sum of the squared components.

import { Vec2 } from "@std/math";

print(new Vec2(3.0, 4.0).lengthSq());
Run in Playground