# math reference

> Numeric helpers and constants.

`math.*` functions are pure and work anywhere. A null argument gives a null result unless noted.

## Functions

### math.abs {#math-abs}

```flowscope
math.abs(value: number) -> same_numeric
```

Returns the absolute value of a number.

`value` keeps its type: an int returns an int and a float returns a float.
Check for null or use `??` to supply a fallback before calling. Null float inputs produce null.

| Parameter | Type |
|---|---|
| `value` | `number` |

**Returns** `same_numeric`

### math.acos {#math-acos}

```flowscope
math.acos(value: float) -> float?
```

Returns the arccosine of a float in radians.

`value` must be in `[-1.0, 1.0]` for a real result. Values outside that range
return null. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.asin {#math-asin}

```flowscope
math.asin(value: float) -> float?
```

Returns the arcsine of a float in radians.

`value` must be in `[-1.0, 1.0]` for a real result. Values outside that range
return null. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.atan {#math-atan}

```flowscope
math.atan(value: float) -> float
```

Returns the arctangent of a number in radians.

The result is between `-math.pi / 2.0` and `math.pi / 2.0`.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.atan2 {#math-atan2}

```flowscope
math.atan2(y: float, x: float) -> float
```

Returns the angle of a vector in radians.

`y` and `x` are the vector's coordinates. The result is from `-math.pi` to
`math.pi`, inclusive.

Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `y` | `float` |
| `x` | `float` |

**Returns** `float`

### math.cbrt {#math-cbrt}

```flowscope
math.cbrt(value: float) -> float
```

Returns the cube root of a number.

`value` can be negative, zero, or positive.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.ceil {#math-ceil}

```flowscope
math.ceil(value: float) -> float
```

Rounds a number up to a whole number.

For example, `1.2` becomes `2.0` and `-1.8` becomes `-1.0`.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.ceilTo {#math-ceilto}

```flowscope
math.ceilTo(value: float, step: float) -> float?
```

Rounds a float up to a multiple of `step`.

`value` is divided by `step`, rounded up, and multiplied by `step`. A zero,
null, or NaN `step` returns null instead of stopping the script with an error.
Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |
| `step` | `float` |

**Returns** `float?`

### math.clamp {#math-clamp}

```flowscope
math.clamp(value: number, min: number, max: number) -> same_numeric
```

Keeps a number within a range.

Returns `value` when it is between `min` and `max`, including both ends.
Below the range it returns `min`; above the range it returns `max`.

Mixing ints and floats gives a float result. `min > max` stops the script with
an error. Check for null or use `??` to supply a fallback before calling.

| Parameter | Type |
|---|---|
| `value` | `number` |
| `min` | `number` |
| `max` | `number` |

**Returns** `same_numeric`

### math.cos {#math-cos}

```flowscope
math.cos(value: float) -> float
```

Returns the cosine of an angle in radians.

`value` is the angle in radians.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.cosh {#math-cosh}

```flowscope
math.cosh(value: float) -> float
```

Returns the hyperbolic cosine of a number.

`value` is the number to calculate from.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.exp {#math-exp}

```flowscope
math.exp(value: float) -> float
```

Returns e raised to a power.

`value` is the exponent. A result too large for a float may be infinite.

Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.floor {#math-floor}

```flowscope
math.floor(value: float) -> float
```

Rounds a number down to a whole number.

For example, `1.8` becomes `1.0` and `-1.2` becomes `-2.0`.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.floorTo {#math-floorto}

```flowscope
math.floorTo(value: float, step: float) -> float?
```

Rounds a float down to a multiple of `step`.

`value` is divided by `step`, rounded down, and multiplied by `step`. A zero,
null, or NaN `step` returns null instead of stopping the script with an error.
Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |
| `step` | `float` |

**Returns** `float?`

### math.isEven {#math-iseven}

```flowscope
math.isEven(value: int) -> bool
```

Tests whether an integer is even.

Returns true when `value % 2 == 0`. Check for null before using a nullable
int. Supported integers range from `math.minInt` (-9223372036854775807) to
`math.maxInt` (9223372036854775807).

| Parameter | Type |
|---|---|
| `value` | `int` |

**Returns** `bool`

### math.isFinite {#math-isfinite}

```flowscope
math.isFinite(value: float?) -> bool
```

Reports whether a number is finite and non-null.

Returns false for null, NaN, and positive or negative infinity; otherwise true.

This check does not change a nullable value's type. Use `x != null` when you
need to use `x` as a non-null value.

| Parameter | Type |
|---|---|
| `value` | `float?` |

**Returns** `bool`

### math.isOdd {#math-isodd}

```flowscope
math.isOdd(value: int) -> bool
```

Tests whether an integer is odd.

Returns true when `value % 2 != 0`. Check for null before using a nullable
int. Supported integers range from `math.minInt` (-9223372036854775807) to
`math.maxInt` (9223372036854775807).

| Parameter | Type |
|---|---|
| `value` | `int` |

**Returns** `bool`

### math.log {#math-log}

```flowscope
math.log(value: float) -> float?
```

Returns the natural logarithm of a float.

`value` must be greater than 0.0 for a real result. Values at or below 0.0
return null. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.log10 {#math-log10}

```flowscope
math.log10(value: float) -> float?
```

Returns the base-10 logarithm of a float.

`value` must be greater than 0.0 for a real result. Values at or below 0.0
return null. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.log2 {#math-log2}

```flowscope
math.log2(value: float) -> float?
```

Returns the base-2 logarithm of a float.

`value` must be greater than 0.0 for a real result. Values at or below 0.0
return null. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.max {#math-max}

```flowscope
math.max(value: number, values: number...) -> same_numeric
```

Returns the largest of one or more numbers.

Pass the first number as `value` and any others as `values`. Mixing ints and
floats gives a float result.

Check for null or use `??` to supply a fallback before calling. NaN inputs produce null.

| Parameter | Type |
|---|---|
| `value` | `number` |
| `values` | `number` |

**Returns** `same_numeric`

### math.min {#math-min}

```flowscope
math.min(value: number, values: number...) -> same_numeric
```

Returns the smallest of one or more numbers.

Pass the first number as `value` and any others as `values`. Mixing ints and
floats gives a float result.

Check for null or use `??` to supply a fallback before calling. NaN inputs produce null.

| Parameter | Type |
|---|---|
| `value` | `number` |
| `values` | `number` |

**Returns** `same_numeric`

### math.pow {#math-pow}

```flowscope
math.pow(base: float, exponent: float) -> float?
```

Raises a number to a power.

Returns `base` raised to `exponent`, as a float. Inputs with no real-number
result, such as a negative base with a fractional exponent, return null.

Check for null or use `??` to supply a fallback before calling.

| Parameter | Type |
|---|---|
| `base` | `float` |
| `exponent` | `float` |

**Returns** `float?`

### math.randomFloat {#math-randomfloat}

```flowscope
math.randomFloat(min: float, max: float) -> float
```

Returns a random float from `min` up to, but not including, `max`.

Both bounds are required. Every equal-sized part of the range is equally
likely. `min >= max` stops the script with an error.

Call this inside a handler. Replaying the same script uses the same sequence
of random values.

| Parameter | Type |
|---|---|
| `min` | `float` |
| `max` | `float` |

**Returns** `float`

**Available in** Handlers and functions called from handlers.

### math.randomInt {#math-randomint}

```flowscope
math.randomInt(min: int, max: int) -> int
```

Returns a random whole number between `min` and `max`, including both.

Both bounds are required. Every integer in the range is equally likely.
`min > max` stops the script with an error. Bounds must be within `math.minInt`
(-9223372036854775807) and `math.maxInt` (9223372036854775807).

Replaying the same script uses the same sequence of random values.

| Parameter | Type |
|---|---|
| `min` | `int` |
| `max` | `int` |

**Returns** `int`

**Available in** Handlers and functions called from handlers.

### math.round {#math-round}

```flowscope
math.round(value: number, decimals: int = 0) -> float
```

Rounds a number to a chosen number of decimal places.

`value` can be an int or float; the result is always a float. `decimals`
defaults to 0, which rounds to a whole number. Negative `decimals` round to
tens, hundreds, and so on.

Check for null or use `??` to supply a fallback before calling. NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `number` |
| `decimals` | `int` |

**Returns** `float`

### math.roundTo {#math-roundto}

```flowscope
math.roundTo(value: float, step: float) -> float?
```

Rounds a float to the nearest multiple of `step`.

`value` is divided by `step`, rounded to the nearest integer value, and
multiplied by `step`. A zero, null, or NaN `step` returns null instead of
stopping the script with an error. Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |
| `step` | `float` |

**Returns** `float?`

### math.safeDiv {#math-safediv}

```flowscope
math.safeDiv(num: float?, den: float?, fallback: float = 0) -> float?
```

Returns a division result with a fallback for zero or missing denominators.

`num` is the numerator. `den` is the denominator; zero or null `den` returns
`fallback`. Null `num` returns null because the numerator is missing.
Otherwise the result is `num / den`.

| Parameter | Type |
|---|---|
| `num` | `float?` |
| `den` | `float?` |
| `fallback` | `float` |

**Returns** `float?`

### math.sign {#math-sign}

```flowscope
math.sign(value: float) -> float
```

Returns `-1.0`, `0.0`, or `1.0` for a number's sign.

Returns `-1.0` for negative values, `1.0` for positive values, and `0.0` for
both `0.0` and `-0.0`.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.sin {#math-sin}

```flowscope
math.sin(value: float) -> float
```

Returns the sine of an angle in radians.

`value` is the angle in radians.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.sinh {#math-sinh}

```flowscope
math.sinh(value: float) -> float
```

Returns the hyperbolic sine of a number.

`value` is the number to calculate from.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.sqrt {#math-sqrt}

```flowscope
math.sqrt(value: float) -> float?
```

Returns the square root of a float.

`value` must be non-negative for a real result. Negative values produce null.
Check for null before calling.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float?`

### math.tan {#math-tan}

```flowscope
math.tan(value: float) -> float
```

Returns the tangent of an angle in radians.

`value` is the angle in radians. Near odd multiples of `math.pi / 2.0`, the
result may be very large or infinite.

Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.tanh {#math-tanh}

```flowscope
math.tanh(value: float) -> float
```

Returns the hyperbolic tangent of a number.

Returns a value from -1.0 to 1.0.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

### math.trunc {#math-trunc}

```flowscope
math.trunc(value: float) -> float
```

Removes the fractional part of a number.

Rounds toward zero: `1.8` becomes `1.0` and `-1.8` becomes `-1.0`.

The result is a float. Check for null or use `??` to supply a fallback before calling. Null or NaN inputs return null.

| Parameter | Type |
|---|---|
| `value` | `float` |

**Returns** `float`

## Constants

| Constant | Type | Value | Description |
|---|---|---|---|
| `math.e` | `float` | `2.718281828459045` | Euler's number, the base of natural logarithms. |
| `math.epsilon` | `float` | `2.220446049250313e-16` | The gap between 1.0 and the next larger float. |
| `math.maxFloat` | `float` | `1.7976931348623157e+308` | The largest finite float. |
| `math.maxInt` | `int` | `9223372036854775807` | The largest supported integer. |
| `math.minFloat` | `float` | `-1.7976931348623157e+308` | The most negative finite float. |
| `math.minInt` | `int` | `-9223372036854775807` | Lowest supported integer value (-9223372036854775807). |
| `math.pi` | `float` | `3.141592653589793` | Pi, the ratio of a circle's circumference to its diameter. |
| `math.tau` | `float` | `6.283185307179586` | Tau, equal to `2.0 * math.pi`. |