tomo/docs/nums.md

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). Numbers can also use the deg suffix to represent degrees, which are converted to radians at compile time (i.e. 180deg == Nums.PI).

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:

abs(n: Num) -> Num

Parameters:

• n: The number whose absolute value is to be computed.

Returns: The absolute value of n.

Example:

>> -3.5:abs()
= 3.5

---

acos

Description: Computes the arc cosine of a number.

Usage:

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:

>> 0.0:acos() // -> (π/2)
= 1.5708

---

acosh

Description: Computes the inverse hyperbolic cosine of a number.

Usage:

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:

>> 1.0:acosh()
= 0

---

asin

Description: Computes the arc sine of a number.

Usage:

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:

>> 0.5:asin()  // -> (π/6)
= 0.5236

---

asinh

Description: Computes the inverse hyperbolic sine of a number.

Usage:

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:

>> 0.0:asinh()
= 0

---

atan2

Description: Computes the arc tangent of the quotient of two numbers.

Usage:

atan2(x: Num, y: Num) -> Num

Parameters:

• x: The numerator.
• y: The denominator.

Returns: The arc tangent of x/y in radians.

Example:

>> Num.atan2(1, 1) // -> (π/4)
= 0.7854

---

atan

Description: Computes the arc tangent of a number.

Usage:

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:

>> 1.0:atan() // -> (π/4)
= 0.7854

---

atanh

Description: Computes the inverse hyperbolic tangent of a number.

Usage:

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:

>> 0.5:atanh()
= 0.5493

---

cbrt

Description: Computes the cube root of a number.

Usage:

cbrt(x: Num) -> Num

Parameters:

• x: The number for which the cube root is to be calculated.

Returns: The cube root of x.

Example:

>> 27.0:cbrt()
= 3

---

ceil

Description: Rounds a number up to the nearest integer.

Usage:

ceil(x: Num) -> Num

Parameters:

• x: The number to be rounded up.

Returns: The smallest integer greater than or equal to x.

Example:

>> 3.2:ceil()
= 4

---

copysign

Description: Copies the sign of one number to another.

Usage:

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:

>> 3.0:copysign(-1)
= -3

---

cos

Description: Computes the cosine of a number (angle in radians).

Usage:

cos(x: Num) -> Num

Parameters:

• x: The angle in radians.

Returns: The cosine of x.

Example:

>> 0.0:cos()
= 1

---

cosh

Description: Computes the hyperbolic cosine of a number.

Usage:

cosh(x: Num) -> Num

Parameters:

• x: The number for which the hyperbolic cosine is to be calculated.

Returns: The hyperbolic cosine of x.

Example:

>> 0.0:cosh()
= 1

---

erf

Description: Computes the error function of a number.

Usage:

erf(x: Num) -> Num

Parameters:

• x: The number for which the error function is to be calculated.

Returns: The error function of x.

Example:

>> 0.0:erf()
= 0

---

erfc

Description: Computes the complementary error function of a number.

Usage:

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:

>> 0.0:erfc()
= 1

---

exp2

Description: Computes 2^x for a number.

Usage:

exp2(x: Num) -> Num

Parameters:

• x: The exponent.

Returns: The value of 2^x.

Example:

>> 3.0:exp2()
= 8

---

exp

Description: Computes the exponential function e^x for a number.

Usage:

exp(x: Num) -> Num

Parameters:

• x: The exponent.

Returns: The value of e^x.

Example:

>> 1.0:exp()
= 2.7183

---

expm1

Description: Computes e^x - 1 for a number.

Usage:

expm1(x: Num) -> Num

Parameters:

• x: The exponent.

Returns: The value of e^x - 1.

Example:

>> 1.0:expm1()
= 1.7183

---

fdim

Description: Computes the positive difference between two numbers.

Usage:

fdim(x: Num, y: Num) -> Num

Parameters:

• x: The first number.
• y: The second number.

Returns: The positive difference \max(0, x - y).

Example:

fd

>> 5.0:fdim(3)
= 2

---

floor

Description: Rounds a number down to the nearest integer.

Usage:

floor(x: Num) -> Num

Parameters:

• x: The number to be rounded down.

Returns: The largest integer less than or equal to x.

Example:

>> 3.7:floor()
= 3

---

format

Description: Formats a number as a string with a specified precision.

Usage:

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:

>> 3.14159:format(precision=2)
= "3.14"

---

from_text

Description: Converts a string representation of a number into a floating-point number.

Usage:

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:

>> 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:

hypot(x: Num, y: Num) -> Num

Parameters:

• x: The first number.
• y: The second number.

Returns: The Euclidean norm of x and y.

Example:

>> Num.hypot(3, 4)
= 5

---

isfinite

Description: Checks if a number is finite.

Usage:

isfinite(n: Num) -> Bool

Parameters:

• n: The number to be checked.

Returns: yes if n is finite, no otherwise.

Example:

>> 1.0:isfinite()
= yes
>> Num.INF:isfinite()
= no

---

isinf

Description: Checks if a number is infinite.

Usage:

isinf(n: Num) -> Bool

Parameters:

• n: The number to be checked.

Returns: yes if n is infinite, no otherwise.

Example:

>> Num.INF:isinf()
= yes
>> 1.0:isinf()
= no

---

isnan

Description: Checks if a number is NaN (Not a Number).

Usage:

isnan(n: Num) -> Bool

Parameters:

• n: The number to be checked.

Returns: yes if n is NaN, no otherwise.

Example:

>> Num.nan():isnan()
= yes
>> 1.0:isnan()
= no

---

j0

Description: Computes the Bessel function of the first kind of order 0.

Usage:

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:

>> 0.0:j0()
= 1

---

j1

Description: Computes the Bessel function of the first kind of order 1.

Usage:

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:

>> 0.0:j1()
= 0

---

log10

Description: Computes the base-10 logarithm of a number.

Usage:

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:

>> 100.0:log10()
= 2

---

log1p

Description: Computes \log(1 + x) for a number.

Usage:

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:

>> 1.0:log1p()
= 0.6931

---

log2

Description: Computes the base-2 logarithm of a number.

Usage:

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:

>> 8.0:log2()
= 3

---

log

Description: Computes the natural logarithm (base e) of a number.

Usage:

log(x: Num) -> Num

Parameters:

• x: The number for which the natural logarithm is to be calculated.

Returns: The natural logarithm of x.

Example:

>> Num.E:log()
= 1

---

logb

Description: Computes the binary exponent (base-2 logarithm) of a number.

Usage:

logb(x: Num) -> Num

Parameters:

• x: The number for which the binary exponent is to be calculated.

Returns: The binary exponent of x.

Example:

>> 8.0:logb()
= 3

---

mix

Description: Interpolates between two numbers based on a given amount.

Usage:

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:

>> 0.5:mix(10, 20)
= 15
>> 0.25:mix(10, 20)
= 12.5

---

nan

Description: Generates a NaN (Not a Number) value.

Usage:

nan(tag: Text = "") -> Num

Parameters:

• tag: An optional tag to describe the NaN. Default is an empty string.

Returns: A NaN value.

Example:

>> 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:

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:

>> 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:

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:

>> 1.0:nextafter(1.1)
= 1.0000000000000002

---

random

Description: Generates a random floating-point number.

Usage:

random() -> Num

Parameters: None

Returns: A random floating-point number between 0 and 1.

Example:

>> Num.random()
= 0.4521

---

rint

Description: Rounds a number to the nearest integer, with ties rounded to the nearest even integer.

Usage:

rint(x: Num) -> Num

Parameters:

• x: The number to be rounded.

Returns: The nearest integer value of x.

Example:

>> 3.5:rint()
= 4
>> 2.5:rint()
= 2

---

round

Description: Rounds a number to the nearest whole number integer.

Usage:

round(x: Num) -> Num

Parameters:

• x: The number to be rounded.

Returns: The nearest integer value of x.

Example:

>> 2.3:round()
= 2
>> 2.7:round()
= 3

---

scientific

Description: Formats a number in scientific notation with a specified precision.

Usage:

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:

>> 12345.6789:scientific(precision=2)
= "1.23e+04"

---

significand

Description: Extracts the significand (or mantissa) of a number.

Usage:

significand(x: Num) -> Num

Parameters:

• x: The number from which to extract the significand.

Returns: The significand of x.

Example:

>> 1234.567:significand()
= 0.1234567

---

sin

Description: Computes the sine of a number (angle in radians).

Usage:

sin(x: Num) -> Num

Parameters:

• x: The angle in radians.

Returns: The sine of x.

Example:

>> 0.0:sin()
= 0

---

sinh

Description: Computes the hyperbolic sine of a number.

Usage:

sinh(x: Num) -> Num

Parameters:

• x: The number for which the hyperbolic sine is to be calculated.

Returns: The hyperbolic sine of x.

Example:

>> 0.0:sinh()
= 0

---

sqrt

Description: Computes the square root of a number.

Usage:

sqrt(x: Num) -> Num

Parameters:

• x: The number for which the square root is to be calculated.

Returns: The square root of x.

Example:

>> 16.0:sqrt()
= 4

---

tan

Description: Computes the tangent of a number (angle in radians).

Usage:

tan(x: Num) -> Num

Parameters:

• x: The angle in radians.

Returns: The tangent of x.

Example:

>> 0.0:tan()
= 0

---

tanh

Description: Computes the hyperbolic tangent of a number.

Usage:

tanh(x: Num) -> Num

Parameters:

• x: The number for which the hyperbolic tangent is to be calculated.

Returns: The hyperbolic tangent of x.

Example:

>> 0.0:tanh()
= 0

---

tgamma

Description: Computes the gamma function of a number.

Usage:

tgamma(x: Num) -> Num

Parameters:

• x: The number for which the gamma function is to be calculated.

Returns: The gamma function of x.

Example:

>> 1.0:tgamma()
= 1

---

trunc

Description: Truncates a number to the nearest integer towards zero.

Usage:

trunc(x: Num) -> Num

Parameters:

• x: The number to be truncated.

Returns: The integer part of x towards zero.

Example:

>> 3.7:trunc()
= 3
>> (-3.7):trunc()
= -3

---

y0

Description: Computes the Bessel function of the second kind of order 0.

Usage:

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:

>> 1.0:y0()
= -0.7652

---

y1

Description: Computes the Bessel function of the second kind of order 1.

Usage:

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:

>> 1.0:y1()
= 0.4401

---

clamped

Description:
Returns the given number clamped between two values so that it is within that range.

Usage:

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:

>> 2.5:clamped(5.5, 10.5)
= 5.5