# math

> Math utilities — basic arithmetic, trig, logarithms, random, constants, bitwise ops, clamping, and interpolation.

# math

Numeric helpers grouped into submodules for basic arithmetic, trigonometry, logarithms, randomness, constants, bitwise operations, clamping, and interpolation. Import it with `import math`.

## math.basic

| Function | Signature | Description |
| --- | --- | --- |
| `abs` | `math.basic.abs(x: number) → number` | Absolute value (preserves int or float) |
| `sqrt` | `math.basic.sqrt(x: number) → float` | Square root |
| `floor` | `math.basic.floor(x: number) → int` | Round down to an int |
| `ceil` | `math.basic.ceil(x: number) → int` | Round up to an int |
| `round` | `math.basic.round(x: number) → int` | Round to nearest int |
| `min` | `math.basic.min(a: number, b: number) → number` | Smaller of two values |
| `max` | `math.basic.max(a: number, b: number) → number` | Larger of two values |
| `pow` | `math.basic.pow(base: number, exp: number) → float` | `base` raised to `exp` |
| `sign` | `math.basic.sign(x: number) → int` | -1, 0, or 1 |
| `clamp` | `math.basic.clamp(value: number, min: number, max: number) → float` | Clamp value to the range |

## math.trig

| Function | Signature | Description |
| --- | --- | --- |
| `sin` | `math.trig.sin(x: number) → float` | Sine (radians) |
| `cos` | `math.trig.cos(x: number) → float` | Cosine (radians) |
| `tan` | `math.trig.tan(x: number) → float` | Tangent (radians) |
| `asin` | `math.trig.asin(x: number) → float` | Arcsine |
| `acos` | `math.trig.acos(x: number) → float` | Arccosine |
| `atan` | `math.trig.atan(x: number) → float` | Arctangent |
| `atan2` | `math.trig.atan2(y: number, x: number) → float` | Two-argument arctangent |
| `deg` | `math.trig.deg(radians: number) → float` | Radians to degrees |
| `rad` | `math.trig.rad(degrees: number) → float` | Degrees to radians |

## math.log

| Function | Signature | Description |
| --- | --- | --- |
| `log` | `math.log.log(x: number) → float` | Natural logarithm |
| `log2` | `math.log.log2(x: number) → float` | Base-2 logarithm |
| `log10` | `math.log.log10(x: number) → float` | Base-10 logarithm |
| `exp` | `math.log.exp(x: number) → float` | e raised to `x` |
| `exp2` | `math.log.exp2(x: number) → float` | 2 raised to `x` |

## math.random

| Function | Signature | Description |
| --- | --- | --- |
| `float` | `math.random.float() → float` | Random float in [0, 1) |
| `int` | `math.random.int() → int` | Random non-negative int |
| `intn` | `math.random.intn(n: int) → int` | Random int in [0, n) (n must be > 0) |
| `seed` | `math.random.seed(seed: int) → void` | Seed the generator |

## math.constants

| Constant | Type | Value |
| --- | --- | --- |
| `PI` | float | Pi |
| `E` | float | Euler's number |
| `PHI` | float | Golden ratio |
| `Sqrt2` | float | Square root of 2 |
| `Ln2` | float | Natural log of 2 |
| `Inf` | float | Positive infinity |
| `NaN` | float | Not-a-number |

## math.bitwise

| Function | Signature | Description |
| --- | --- | --- |
| `and` | `math.bitwise.and(a: int, b: int) → int` | Bitwise AND |
| `or` | `math.bitwise.or(a: int, b: int) → int` | Bitwise OR |
| `xor` | `math.bitwise.xor(a: int, b: int) → int` | Bitwise XOR |
| `not` | `math.bitwise.not(a: int) → int` | Bitwise NOT |
| `shl` | `math.bitwise.shl(a: int, n: int) → int` | Left shift by `n` bits |
| `shr` | `math.bitwise.shr(a: int, n: int) → int` | Right shift by `n` bits |
| `popcount` | `math.bitwise.popcount(a: int) → int` | Number of set bits |

## math.clamp

| Function | Signature | Description |
| --- | --- | --- |
| `clamp` | `math.clamp.clamp(value: number, min: number, max: number) → float` | Clamp to the range as a float |
| `clampInt` | `math.clamp.clampInt(value: int, min: int, max: int) → int` | Clamp to the range as an int |
| `clampFloat` | `math.clamp.clampFloat(value: number, min: number, max: number) → float` | Clamp to the range as a float |

## math.lerp

| Function | Signature | Description |
| --- | --- | --- |
| `lerp` | `math.lerp.lerp(a: number, b: number, t: number) → float` | Linear interpolation between `a` and `b` |
| `invLerp` | `math.lerp.invLerp(a: number, b: number, value: number) → float` | Inverse lerp: where `value` falls in [a, b] |
| `remap` | `math.lerp.remap(value: number, inMin, inMax, outMin, outMax: number) → float` | Remap from one range to another |
| `smoothstep` | `math.lerp.smoothstep(edge0: number, edge1: number, x: number) → float` | Smooth Hermite interpolation in [0, 1] |

## Top-level shortcuts

Convenience aliases on `math` itself: `math.PI`, `math.E`, and `math.abs`, `math.sqrt`, `math.floor`, `math.ceil`, `math.pow`, `math.min`, `math.max` (same behavior as the `math.basic` equivalents).

## Example

```goost
import math

print(math.basic.clamp(15, 0, 10))      // 10
print(math.trig.deg(math.constants.PI)) // 180

// pick a random index
math.random.seed(42)
let i = math.random.intn(5)              // 0..4

// blend two values
print(math.lerp.lerp(0, 100, 0.25))      // 25
```