Overview
The math operations module provides fundamental mathematical utilities for constraining numeric values.
Functions
clamp
Constrains a value between a minimum and maximum bound.
function clamp<T extends number | bigint>(x: T, min: T, max: T): T
The minimum allowed value
The maximum allowed value
The clamped value, constrained between min and max
import { clamp } from "@temelj/math";
console.log(clamp(50, 0, 100)); // 50
console.log(clamp(-10, 0, 100)); // 0
console.log(clamp(150, 0, 100)); // 100
// Works with bigints too
console.log(clamp(50n, 0n, 100n)); // 50n
clampWithOverflow
Clamps a value with wrapping overflow behavior, creating a circular range.
function clampWithOverflow<T extends number | bigint>(x: T, min: T, max: T): T
The minimum bound of the range
The maximum bound of the range
The value wrapped within the range using modulo arithmetic
- If
x < min, it wraps from the max end: max - ((min - x) % (max - min))
- If
x > max, it wraps from the min end: min + ((x - max) % (max - min))
- If
x is within bounds, it returns x unchanged
Example:
import { clampWithOverflow } from "@temelj/math";
// Value within range
console.log(clampWithOverflow(50, 0, 100)); // 50
// Value exceeds max, wraps around
console.log(clampWithOverflow(110, 0, 100)); // 10
console.log(clampWithOverflow(250, 0, 100)); // 50
// Value below min, wraps around from max
console.log(clampWithOverflow(-10, 0, 100)); // 90
console.log(clampWithOverflow(-50, 0, 100)); // 50
- Circular angles (0-360 degrees)
- Array index wrapping
- Cyclic sequences
- Game coordinates with world wrapping
Example - Circular navigation:
// Navigate through items with wrapping
function nextIndex(current: number, total: number): number {
return clampWithOverflow(current + 1, 0, total);
}
function previousIndex(current: number, total: number): number {
return clampWithOverflow(current - 1, 0, total);
}
const items = ['A', 'B', 'C'];
let index = 2;
index = nextIndex(index, items.length); // 0 (wraps around)
index = previousIndex(index, items.length); // 2 (wraps backward)