# Math Library

Mathematical functions beyond basic arithmetic. Provides safe wrappers around numeric builtins that handle edge cases (division by zero, domain errors) by returning `MAYBE` types. Import it into L4 files with `IMPORT math`.

### Location

[jl4-core/libraries/math.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/math.l4)

### Constants

- `EULER` - Euler's number (2.718281828459045)
- `TAN_EPSILON` - Threshold for detecting tan asymptotes

### Functions

| Function    | Signature               | Description                       |
| ----------- | ----------------------- | --------------------------------- |
| `exp`       | `NUMBER → NUMBER`       | e^x via `EXPONENT EULER x`        |
| `ln`        | `NUMBER → MAYBE NUMBER` | Natural log (NOTHING if x ≤ 0)    |
| `log10`     | `NUMBER → MAYBE NUMBER` | Base-10 log (NOTHING if x ≤ 0)    |
| `sqrt`      | `NUMBER → MAYBE NUMBER` | Square root (NOTHING if x < 0)    |
| `absNumber` | `NUMBER → NUMBER`       | Absolute value                    |
| `sin`       | `NUMBER → MAYBE NUMBER` | Sine (always JUST)                |
| `cos`       | `NUMBER → MAYBE NUMBER` | Cosine (always JUST)              |
| `tan`       | `NUMBER → MAYBE NUMBER` | Tangent (NOTHING near asymptotes) |
| `asin`      | `NUMBER → MAYBE NUMBER` | Arc sine (NOTHING if \|x\| > 1)   |
| `acos`      | `NUMBER → MAYBE NUMBER` | Arc cosine (NOTHING if \|x\| > 1) |
| `atan`      | `NUMBER → MAYBE NUMBER` | Arc tangent (always JUST)         |

**Note:** All trigonometric functions expect/return angles in **radians**.

### Example: Math Functions



```l4-file
-- Math Example: Mathematical functions with safe error handling
IMPORT math

-- Euler's constant
#EVAL EULER  -- 2.718281828459045

-- Exponential function
DECIDE `exponential growth` IS exp 2
#EVAL `exponential growth`  -- e^2 ≈ 7.389

-- Safe logarithms (return MAYBE to handle domain errors)
DECIDE `valid natural log` IS ln 10
#EVAL `valid natural log`  -- JUST 2.302...

DECIDE `invalid natural log` IS ln (0 MINUS 5)
#EVAL `invalid natural log`  -- NOTHING (negative input)

DECIDE `base 10 logarithm` IS log10 100
#EVAL `base 10 logarithm`  -- JUST 2

-- Safe square root
DECIDE `valid square root` IS sqrt 16
#EVAL `valid square root`  -- JUST 4

DECIDE `invalid square root` IS sqrt (0 MINUS 4)
#EVAL `invalid square root`  -- NOTHING (negative input)

-- Absolute value
DECIDE `absolute of positive` IS absNumber 42
#EVAL `absolute of positive`  -- 42

DECIDE `absolute of negative` IS absNumber (0 MINUS 42)
#EVAL `absolute of negative`  -- 42

-- Trigonometric functions (angles in radians)
DECIDE `sine of zero` IS sin 0
#EVAL `sine of zero`  -- JUST 0

DECIDE `cosine of zero` IS cos 0
#EVAL `cosine of zero`  -- JUST 1

-- Tangent with asymptote protection
DECIDE `tangent of zero` IS tan 0
#EVAL `tangent of zero`  -- JUST 0

-- Inverse trig with domain checking
DECIDE `valid arcsine` IS asin 0.5
#EVAL `valid arcsine`  -- JUST 0.523... (π/6)

DECIDE `invalid arcsine` IS asin 2
#EVAL `invalid arcsine`  -- NOTHING (|x| > 1)

-- Using fromMaybe to extract with default
DECIDE `safe extracted value` IS fromMaybe 0 (sqrt 25)
#EVAL `safe extracted value`  -- 5

DECIDE `value with default` IS fromMaybe 0 (sqrt (0 MINUS 1))
#EVAL `value with default`  -- 0 (used default)
```



**See [math.l4](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/math.l4) source for all functions.**