diff options
Diffstat (limited to 'api/nums.md')
| -rw-r--r-- | api/nums.md | 1374 |
1 files changed, 0 insertions, 1374 deletions
diff --git a/api/nums.md b/api/nums.md deleted file mode 100644 index 5b258010..00000000 --- a/api/nums.md +++ /dev/null @@ -1,1374 +0,0 @@ -# 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 -``` |