Math & Calculations (std.math)

The std.math module, alongside the globally available mathematical methods on Int and Float primitives, provides robust native calculation capabilities in Flame.

---

Global Math Methods on Primitives

Flame’s primitive numeric types (Int and Float) have built-in mathematical methods available directly on their values.

Absolute Value

Returns the absolute (non-negative) value.

let a = -10
println(a.abs()) // 10

let b = -3.14
println(b.abs()) // 3.14

Rounding (Floats only)

Floats have .floor(), .ceil(), and .round() methods:

let f = 5.7
println(f.floor()) // 5.0
println(f.ceil())  // 6.0
println(f.round()) // 6.0

Min, Max, and Clamp

Easily compare or limit bounds on numbers.

let x = 15

// Min & Max
println(x.min(10)) // 10
println(x.max(20)) // 20

// Clamp keeps the number within [min, max]
println(x.clamp(0, 10))  // 10
println(x.clamp(20, 30)) // 20

Square Root and Power

let n = 16
println(n.sqrt()) // 4.0

let base = 5
println(base.pow(3)) // 125

---

The std.math Module

For more advanced mathematical calculations or when you prefer a functional approach instead of calling methods on primitives, import the std.math module.

import std.math

// Mathematical Constants
println(math.pi) // 3.141592653589793
println(math.e)  // 2.718281828459045

// Basic Operations
println(math.abs(-10))       // 10
println(math.sqrt(16))       // 4.0
println(math.min(10, 20))    // 10
println(math.max(10, 20))    // 20

// Trigonometry
let angle = math.pi / 2.0
println(math.sin(angle)) // 1.0
println(math.cos(angle)) // 0.0
// Note: tangent is available if implemented, e.g. math.tan(0)

// Random Numbers
// Generates a random integer between min and max (inclusive)
let dice = math.randomInt(1, 6)
println($"Rolled a {dice}")

// Generates a random float between 0.0 and 1.0
let chance = math.randomFloat()

API Summary Table

Primitive Numeric Methods

Method	Available On	Description
.abs()	Int, Float	Returns absolute value.
.floor()	Float	Rounds down to the nearest integer.
.ceil()	Float	Rounds up to the nearest integer.
.round()	Float	Rounds to the nearest integer.
.sqrt()	Int, Float	Returns the square root.
.pow(exp)	Int, Float	Returns number to the given power.
.min(y)	Int, Float	Returns the smaller of two values.
.max(y)	Int, Float	Returns the larger of two values.
.clamp(min, max)	Int, Float	Restricts value between min and max bounds.

std.math Methods

Method / Constant	Description
math.pi	The constant Pi (π).
math.e	Euler’s number (e).
math.abs(val)	Returns the absolute value of the number.
math.sqrt(val)	Returns the square root of the number.
math.min(x, y)	Returns the smaller of the two values.
math.max(x, y)	Returns the larger of the two values.
math.sin(rad)	Sine of an angle in radians.
math.cos(rad)	Cosine of an angle in radians.
math.randomInt(min, max)	Random integer between min and max.
math.randomFloat()	Random float between 0.0 and 1.0.