From 67e8f2dea0d4eec20a839d47f1fa6302a4a5f733 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Mon, 19 Aug 2024 00:23:02 -0400 Subject: Move docs into one folder --- docs/nums.md | 1374 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1374 insertions(+) create mode 100644 docs/nums.md (limited to 'docs/nums.md') 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 +``` -- cgit v1.2.3