1 files changed, 1374 insertions, 0 deletions
diff --git a/docs/nums.md b/docs/nums.md
new file mode 100644
index 00000000..5b258010
--- /dev/null
+++ b/docs/nums.md
@@ -0,0 +1,1374 @@
+# Nums
+
+Tomo has two floating point number types: `Num` (64-bit, AKA `double`) and
+`Num32` (32-bit, AKA `float`). Num literals can have a decimal point (e.g.
+`5.`), a scientific notation suffix (e.g. `1e8`) or a percent sign. Numbers
+that end in a percent sign are divided by 100 at compile time (i.e. `5% ==
+0.05`).
+
+Nums support the standard math operations (`x+y`, `x-y`, `x*y`, `x/y`) as well as
+powers/exponentiation (`x^y`) and modulus (`x mod y` and `x mod1 y`).
+
+# Num Functions
+
+Each Num type has its own version of the following functions. Functions can be
+called either on the type itself: `Num.sqrt(x)` or as a method call:
+`x:sqrt()`. Method call syntax is preferred.
+
+## Constants
+
+- **`1_PI`**: \( \frac{1}{\pi} \)
+- **`2_PI`**: \( 2 \times \pi \)
+- **`2_SQRTPI`**: \( 2 \times \sqrt{\pi} \)
+- **`E`**: Base of natural logarithms (\( e \))
+- **`INF`**: Positive infinity
+- **`LN10`**: Natural logarithm of 10
+- **`LN2`**: Natural logarithm of 2
+- **`LOG2E`**: Logarithm base 2 of \( e \)
+- **`PI`**: Pi (\( \pi \))
+- **`PI_2`**: \( \frac{\pi}{2} \)
+- **`PI_4`**: \( \frac{\pi}{4} \)
+- **`SQRT1_2`**: \( \sqrt{\frac{1}{2}} \)
+- **`SQRT2`**: \( \sqrt{2} \)
+- **`TAU`**: Tau (\( 2 \times \pi \))
+
+## Functions
+
+### `abs`
+
+**Description:**
+Calculates the absolute value of a number.
+
+**Usage:**
+```tomo
+abs(n: Num) -> Num
+```
+
+**Parameters:**
+
+- `n`: The number whose absolute value is to be computed.
+
+**Returns:**
+The absolute value of `n`.
+
+**Example:**
+```tomo
+>> -3.5:abs()
+= 3.5
+```
+
+---
+
+### `acos`
+
+**Description:**
+Computes the arc cosine of a number.
+
+**Usage:**
+```tomo
+acos(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the arc cosine is to be calculated.
+
+**Returns:**
+The arc cosine of `x` in radians.
+
+**Example:**
+```tomo
+>> 0.0:acos() // -> (π/2)
+= 1.5708
+```
+
+---
+
+### `acosh`
+
+**Description:**
+Computes the inverse hyperbolic cosine of a number.
+
+**Usage:**
+```tomo
+acosh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the inverse hyperbolic cosine is to be calculated.
+
+**Returns:**
+The inverse hyperbolic cosine of `x`.
+
+**Example:**
+```tomo
+>> 1.0:acosh()
+= 0
+```
+
+---
+
+### `asin`
+
+**Description:**
+Computes the arc sine of a number.
+
+**Usage:**
+```tomo
+asin(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the arc sine is to be calculated.
+
+**Returns:**
+The arc sine of `x` in radians.
+
+**Example:**
+```tomo
+>> 0.5:asin()  // -> (π/6)
+= 0.5236
+```
+
+---
+
+### `asinh`
+
+**Description:**
+Computes the inverse hyperbolic sine of a number.
+
+**Usage:**
+```tomo
+asinh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the inverse hyperbolic sine is to be calculated.
+
+**Returns:**
+The inverse hyperbolic sine of `x`.
+
+**Example:**
+```tomo
+>> 0.0:asinh()
+= 0
+```
+
+---
+
+### `atan2`
+
+**Description:**
+Computes the arc tangent of the quotient of two numbers.
+
+**Usage:**
+```tomo
+atan2(x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The numerator.
+- `y`: The denominator.
+
+**Returns:**
+The arc tangent of `x/y` in radians.
+
+**Example:**
+```tomo
+>> Num.atan2(1, 1) // -> (π/4)
+= 0.7854
+```
+
+---
+
+### `atan`
+
+**Description:**
+Computes the arc tangent of a number.
+
+**Usage:**
+```tomo
+atan(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the arc tangent is to be calculated.
+
+**Returns:**
+The arc tangent of `x` in radians.
+
+**Example:**
+```tomo
+>> 1.0:atan() // -> (π/4)
+= 0.7854
+```
+
+---
+
+### `atanh`
+
+**Description:**
+Computes the inverse hyperbolic tangent of a number.
+
+**Usage:**
+```tomo
+atanh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the inverse hyperbolic tangent is to be calculated.
+
+**Returns:**
+The inverse hyperbolic tangent of `x`.
+
+**Example:**
+```tomo
+>> 0.5:atanh()
+= 0.5493
+```
+
+---
+
+### `cbrt`
+
+**Description:**
+Computes the cube root of a number.
+
+**Usage:**
+```tomo
+cbrt(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the cube root is to be calculated.
+
+**Returns:**
+The cube root of `x`.
+
+**Example:**
+```tomo
+>> 27.0:cbrt()
+= 3
+```
+
+---
+
+### `ceil`
+
+**Description:**
+Rounds a number up to the nearest integer.
+
+**Usage:**
+```tomo
+ceil(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to be rounded up.
+
+**Returns:**
+The smallest integer greater than or equal to `x`.
+
+**Example:**
+```tomo
+>> 3.2:ceil()
+= 4
+```
+
+---
+
+### `copysign`
+
+**Description:**
+Copies the sign of one number to another.
+
+**Usage:**
+```tomo
+copysign(x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number whose magnitude will be copied.
+- `y`: The number whose sign will be copied.
+
+**Returns:**
+A number with the magnitude of `x` and the sign of `y`.
+
+**Example:**
+```tomo
+>> 3.0:copysign(-1)
+= -3
+```
+
+---
+
+### `cos`
+
+**Description:**
+Computes the cosine of a number (angle in radians).
+
+**Usage:**
+```tomo
+cos(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The angle in radians.
+
+**Returns:**
+The cosine of `x`.
+
+**Example:**
+```tomo
+>> 0.0:cos()
+= 1
+```
+
+---
+
+### `cosh`
+
+**Description:**
+Computes the hyperbolic cosine of a number.
+
+**Usage:**
+```tomo
+cosh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the hyperbolic cosine is to be calculated.
+
+**Returns:**
+The hyperbolic cosine of `x`.
+
+**Example:**
+```tomo
+>> 0.0:cosh()
+= 1
+```
+
+---
+
+### `erf`
+
+**Description:**
+Computes the error function of a number.
+
+**Usage:**
+```tomo
+erf(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the error function is to be calculated.
+
+**Returns:**
+The error function of `x`.
+
+**Example:**
+```tomo
+>> 0.0:erf()
+= 0
+```
+
+---
+
+### `erfc`
+
+**Description:**
+Computes the complementary error function of a number.
+
+**Usage:**
+```tomo
+erfc(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the complementary error function is to be calculated.
+
+**Returns:**
+The complementary error function of `x`.
+
+**Example:**
+```tomo
+>> 0.0:erfc()
+= 1
+```
+
+---
+
+### `exp2`
+
+**Description:**
+Computes \( 2^x \) for a number.
+
+**Usage:**
+```tomo
+exp2(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The exponent.
+
+**Returns:**
+The value of \( 2^x \).
+
+**Example:**
+```tomo
+>> 3.0:exp2()
+= 8
+```
+
+---
+
+### `exp`
+
+**Description:**
+Computes the exponential function \( e^x \) for a number.
+
+**Usage:**
+```tomo
+exp(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The exponent.
+
+**Returns:**
+The value of \( e^x \).
+
+**Example:**
+```tomo
+>> 1.0:exp()
+= 2.7183
+```
+
+---
+
+### `expm1`
+
+**Description:**
+Computes \( e^x - 1 \) for a number.
+
+**Usage:**
+```tomo
+expm1(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The exponent.
+
+**Returns:**
+The value of \( e^x - 1 \).
+
+**Example:**
+```tomo
+>> 1.0:expm1()
+= 1.7183
+```
+
+---
+
+### `fdim`
+
+**Description:**
+Computes the positive difference between two numbers.
+
+**Usage:**
+```tomo
+fdim(x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The first number.
+- `y`: The second number.
+
+**Returns:**
+The positive difference \( \max(0, x - y) \).
+
+**Example:**
+```tomo
+fd
+
+>> 5.0:fdim(3)
+= 2
+```
+
+---
+
+### `floor`
+
+**Description:**
+Rounds a number down to the nearest integer.
+
+**Usage:**
+```tomo
+floor(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to be rounded down.
+
+**Returns:**
+The largest integer less than or equal to `x`.
+
+**Example:**
+```tomo
+>> 3.7:floor()
+= 3
+```
+
+---
+
+### `format`
+
+**Description:**
+Formats a number as a string with a specified precision.
+
+**Usage:**
+```tomo
+format(n: Num, precision: Int = 0) -> Text
+```
+
+**Parameters:**
+
+- `n`: The number to be formatted.
+- `precision`: The number of decimal places. Default is `0`.
+
+**Returns:**
+A string representation of the number with the specified precision.
+
+**Example:**
+```tomo
+>> 3.14159:format(precision=2)
+= "3.14"
+```
+
+---
+
+### `from_text`
+
+**Description:**
+Converts a string representation of a number into a floating-point number.
+
+**Usage:**
+```tomo
+from_text(text: Text, the_rest: Text = "!&Text") -> Num
+```
+
+**Parameters:**
+
+- `text`: The string containing the number.
+- `the_rest`: A string indicating what to return if the conversion fails. Default is `"!&Text"`.
+
+**Returns:**
+The number represented by the string.
+
+**Example:**
+```tomo
+>> Num.from_text("3.14")
+= 3.14
+>> Num.from_text("1e3")
+= 1000
+```
+
+---
+
+### `hypot`
+
+**Description:**
+Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers.
+
+**Usage:**
+```tomo
+hypot(x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The first number.
+- `y`: The second number.
+
+**Returns:**
+The Euclidean norm of `x` and `y`.
+
+**Example:**
+```tomo
+>> Num.hypot(3, 4)
+= 5
+```
+
+---
+
+### `isfinite`
+
+**Description:**
+Checks if a number is finite.
+
+**Usage:**
+```tomo
+isfinite(n: Num) -> Bool
+```
+
+**Parameters:**
+
+- `n`: The number to be checked.
+
+**Returns:**
+`yes` if `n` is finite, `no` otherwise.
+
+**Example:**
+```tomo
+>> 1.0:isfinite()
+= yes
+>> Num.INF:isfinite()
+= no
+```
+
+---
+
+### `isinf`
+
+**Description:**
+Checks if a number is infinite.
+
+**Usage:**
+```tomo
+isinf(n: Num) -> Bool
+```
+
+**Parameters:**
+
+- `n`: The number to be checked.
+
+**Returns:**
+`yes` if `n` is infinite, `no` otherwise.
+
+**Example:**
+```tomo
+>> Num.INF:isinf()
+= yes
+>> 1.0:isinf()
+= no
+```
+
+---
+
+### `isnan`
+
+**Description:**
+Checks if a number is NaN (Not a Number).
+
+**Usage:**
+```tomo
+isnan(n: Num) -> Bool
+```
+
+**Parameters:**
+
+- `n`: The number to be checked.
+
+**Returns:**
+`yes` if `n` is NaN, `no` otherwise.
+
+**Example:**
+```tomo
+>> Num.nan():isnan()
+= yes
+>> 1.0:isnan()
+= no
+```
+
+---
+
+### `j0`
+
+**Description:**
+Computes the Bessel function of the first kind of order 0.
+
+**Usage:**
+```tomo
+j0(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the Bessel function is to be calculated.
+
+**Returns:**
+The Bessel function of the first kind of order 0 of `x`.
+
+**Example:**
+```tomo
+>> 0.0:j0()
+= 1
+```
+
+---
+
+### `j1`
+
+**Description:**
+Computes the Bessel function of the first kind of order 1.
+
+**Usage:**
+```tomo
+j1(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the Bessel function is to be calculated.
+
+**Returns:**
+The Bessel function of the first kind of order 1 of `x`.
+
+**Example:**
+```tomo
+>> 0.0:j1()
+= 0
+```
+
+---
+
+### `log10`
+
+**Description:**
+Computes the base-10 logarithm of a number.
+
+**Usage:**
+```tomo
+log10(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the base-10 logarithm is to be calculated.
+
+**Returns:**
+The base-10 logarithm of `x`.
+
+**Example:**
+```tomo
+>> 100.0:log10()
+= 2
+```
+
+---
+
+### `log1p`
+
+**Description:**
+Computes \( \log(1 + x) \) for a number.
+
+**Usage:**
+```tomo
+log1p(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which \( \log(1 + x) \) is to be calculated.
+
+**Returns:**
+The value of \( \log(1 + x) \).
+
+**Example:**
+```tomo
+>> 1.0:log1p()
+= 0.6931
+```
+
+---
+
+### `log2`
+
+**Description:**
+Computes the base-2 logarithm of a number.
+
+**Usage:**
+```tomo
+log2(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the base-2 logarithm is to be calculated.
+
+**Returns:**
+The base-2 logarithm of `x`.
+
+**Example:**
+```tomo
+>> 8.0:log2()
+= 3
+```
+
+---
+
+### `log`
+
+**Description:**
+Computes the natural logarithm (base \( e \)) of a number.
+
+**Usage:**
+```tomo
+log(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the natural logarithm is to be calculated.
+
+**Returns:**
+The natural logarithm of `x`.
+
+**Example:**
+```tomo
+>> Num.E:log()
+= 1
+```
+
+---
+
+### `logb`
+
+**Description:**
+Computes the binary exponent (base-2 logarithm) of a number.
+
+**Usage:**
+```tomo
+logb(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the binary exponent is to be calculated.
+
+**Returns:**
+The binary exponent of `x`.
+
+**Example:**
+```tomo
+>> 8.0:logb()
+= 3
+```
+
+---
+
+### `mix`
+
+**Description:**
+Interpolates between two numbers based on a given amount.
+
+**Usage:**
+```tomo
+mix(amount: Num, x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `amount`: The interpolation factor (between `0` and `1`).
+- `x`: The starting number.
+- `y`: The ending number.
+
+**Returns:**
+The interpolated number between `x` and `y` based on `amount`.
+
+**Example:**
+```tomo
+>> 0.5:mix(10, 20)
+= 15
+>> 0.25:mix(10, 20)
+= 12.5
+```
+
+---
+
+### `nan`
+
+**Description:**
+Generates a NaN (Not a Number) value.
+
+**Usage:**
+```tomo
+nan(tag: Text = "") -> Num
+```
+
+**Parameters:**
+
+- `tag`: An optional tag to describe the NaN. Default is an empty string.
+
+**Returns:**
+A NaN value.
+
+**Example:**
+```tomo
+>> Num.nan()
+= NaN
+```
+
+---
+
+### `near`
+
+**Description:**
+Checks if two numbers are approximately equal within specified tolerances. If
+two numbers are within an absolute difference or the ratio between the two is
+small enough, they are considered near each other.
+
+**Usage:**
+```tomo
+near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9) -> Bool
+```
+
+**Parameters:**
+
+- `x`: The first number.
+- `y`: The second number.
+- `ratio`: The relative tolerance. Default is `1e-9`.
+- `min_epsilon`: The absolute tolerance. Default is `1e-9`.
+
+**Returns:**
+`yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise.
+
+**Example:**
+```tomo
+>> 1.0:near(1.000000001)
+= yes
+
+>> 100.0:near(110, ratio=0.1)
+= yes
+
+>> 5.0:near(5.1, min_epsilon=0.1)
+= yes
+```
+
+---
+
+### `nextafter`
+
+**Description:**
+Computes the next representable value after a given number towards a specified direction.
+
+**Usage:**
+```tomo
+nextafter(x: Num, y: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The starting number.
+- `y`: The direction towards which to find the next representable value.
+
+**Returns:**
+The next representable value after `x` in the direction of `y`.
+
+**Example:**
+```tomo
+>> 1.0:nextafter(1.1)
+= 1.0000000000000002
+```
+
+---
+
+### `random`
+
+**Description:**
+Generates a random floating-point number.
+
+**Usage:**
+```tomo
+random() -> Num
+```
+
+**Parameters:**
+None
+
+**Returns:**
+A random floating-point number between 0 and 1.
+
+**Example:**
+```tomo
+>> Num.random()
+= 0.4521
+```
+
+---
+
+### `rint`
+
+**Description:**
+Rounds a number to the nearest integer, with ties rounded to the nearest even integer.
+
+**Usage:**
+```tomo
+rint(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to be rounded.
+
+**Returns:**
+The nearest integer value of `x`.
+
+**Example:**
+```tomo
+>> 3.5:rint()
+= 4
+>> 2.5:rint()
+= 2
+```
+
+---
+
+### `round`
+
+**Description:**
+Rounds a number to the nearest whole number integer.
+
+**Usage:**
+```tomo
+round(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to be rounded.
+
+**Returns:**
+The nearest integer value of `x`.
+
+**Example:**
+```tomo
+>> 2.3:round()
+= 2
+>> 2.7:round()
+= 3
+```
+
+---
+
+### `scientific`
+
+**Description:**
+Formats a number in scientific notation with a specified precision.
+
+**Usage:**
+```tomo
+scientific(n: Num, precision: Int = 0) -> Text
+```
+
+**Parameters:**
+
+- `n`: The number to be formatted.
+- `precision`: The number of decimal places. Default is `0`.
+
+**Returns:**
+A string representation of the number in scientific notation with the specified precision.
+
+**Example:**
+```tomo
+>> 12345.6789:scientific(precision=2)
+= "1.23e+04"
+```
+
+---
+
+### `significand`
+
+**Description:**
+Extracts the significand (or mantissa) of a number.
+
+**Usage:**
+```tomo
+significand(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number from which to extract the significand.
+
+**Returns:**
+The significand of `x`.
+
+**Example:**
+```tomo
+>> 1234.567:significand()
+= 0.1234567
+```
+
+---
+
+### `sin`
+
+**Description:**
+Computes the sine of a number (angle in radians).
+
+**Usage:**
+```tomo
+sin(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The angle in radians.
+
+**Returns:**
+The sine of `x`.
+
+**Example:**
+```tomo
+>> 0.0:sin()
+= 0
+```
+
+---
+
+### `sinh`
+
+**Description:**
+Computes the hyperbolic sine of a number.
+
+**Usage:**
+```tomo
+sinh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the hyperbolic sine is to be calculated.
+
+**Returns:**
+The hyperbolic sine of `x`.
+
+**Example:**
+```tomo
+>> 0.0:sinh()
+= 0
+```
+
+---
+
+### `sqrt`
+
+**Description:**
+Computes the square root of a number.
+
+**Usage:**
+```tomo
+sqrt(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the square root is to be calculated.
+
+**Returns:**
+The square root of `x`.
+
+**Example:**
+```tomo
+>> 16.0:sqrt()
+= 4
+```
+
+---
+
+### `tan`
+
+**Description:**
+Computes the tangent of a number (angle in radians).
+
+**Usage:**
+```tomo
+tan(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The angle in radians.
+
+**Returns:**
+The tangent of `x`.
+
+**Example:**
+```tomo
+>> 0.0:tan()
+= 0
+```
+
+---
+
+### `tanh`
+
+**Description:**
+Computes the hyperbolic tangent of a number.
+
+**Usage:**
+```tomo
+tanh(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the hyperbolic tangent is to be calculated.
+
+**Returns:**
+The hyperbolic tangent of `x`.
+
+**Example:**
+```tomo
+>> 0.0:tanh()
+= 0
+```
+
+---
+
+### `tgamma`
+
+**Description:**
+Computes the gamma function of a number.
+
+**Usage:**
+```tomo
+tgamma(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the gamma function is to be calculated.
+
+**Returns:**
+The gamma function of `x`.
+
+**Example:**
+```tomo
+>> 1.0:tgamma()
+= 1
+```
+
+---
+
+### `trunc`
+
+**Description:**
+Truncates a number to the nearest integer towards zero.
+
+**Usage:**
+```tomo
+trunc(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to be truncated.
+
+**Returns:**
+The integer part of `x` towards zero.
+
+**Example:**
+```tomo
+>> 3.7:trunc()
+= 3
+>> (-3.7):trunc()
+= -3
+```
+
+---
+
+### `y0`
+
+**Description:**
+Computes the Bessel function of the second kind of order 0.
+
+**Usage:**
+```tomo
+y0(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the Bessel function is to be calculated.
+
+**Returns:**
+The Bessel function of the second kind of order 0 of `x`.
+
+**Example:**
+```tomo
+>> 1.0:y0()
+= -0.7652
+```
+
+---
+
+### `y1`
+
+**Description:**
+Computes the Bessel function of the second kind of order 1.
+
+**Usage:**
+```tomo
+y1(x: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number for which the Bessel function is to be calculated.
+
+**Returns:**
+The Bessel function of the second kind of order 1 of `x`.
+
+**Example:**
+```tomo
+>> 1.0:y1()
+= 0.4401
+```
+
+---
+
+## `clamped`
+
+**Description:**  
+Returns the given number clamped between two values so that it is within
+that range.
+
+**Usage:**  
+```tomo
+clamped(x, low, high: Num) -> Num
+```
+
+**Parameters:**
+
+- `x`: The number to clamp.
+- `low`: The lowest value the result can take.
+- `high`: The highest value the result can take.
+
+**Returns:**  
+The first argument clamped between the other two arguments.
+
+**Example:**  
+```tomo
+>> 2.5:clamped(5.5, 10.5)
+= 5.5
+```