Skip to content
ry

Functions over single numbers, integer or double, and eight constants (Num.pi, Num.tau, Num.e, Num.infinity and the integer and double limits). A checked operation returns the failure as a tag where R would return NA, NaN or Inf with a warning; its unchecked twin (Num.add beside Num.add_checked) stops with an error in that case. A NaN result, such as Inf - Inf or Num.sin(Inf), is :Err(:Undefined) from a checked operation and an error from any other. The bit operations work on an I64’s 64-bit two’s complement, and on an R number’s 32 bits when no argument is an I64.

Function Summary
Num.to_str The number as text, with up to 15 significant digits.
Num.compare :LT, :EQ or :GT, comparing first with second.
Num.min The smaller number.
Num.max The larger number.
Num.is_lt Whether first < second.
Num.is_gt Whether first > second.
Num.is_lte Whether first <= second.
Num.is_gte Whether first >= second.
Num.is_approx_eq Whether two numbers are equal within a relative tolerance rtol (default 1e-5) or an absolute tolerance atol (default 1e-8).
Num.is_zero Whether the number is zero.
Num.is_positive Whether the number is greater than zero.
Num.is_negative Whether the number is less than zero.
Num.is_even Whether the number is a whole, even number.
Num.is_odd Whether the number is a whole, odd number.
Num.is_multiple_of Whether first is a whole multiple of second.
Num.is_finite Whether the number is neither infinite nor NaN.
Num.is_infinite Whether the number is Inf or -Inf.
Num.abs The absolute value.
Num.abs_diff The absolute difference of two numbers.
Num.neg The number with its sign flipped.
Num.ceiling Rounds up to a whole number, keeping the number type.
Num.floor Rounds down to a whole number, as an I64.
Num.round Rounds to the nearest whole number, halves away from zero, as an I64.
Num.truncate Drops the fraction, rounding toward zero, as an I64.
Num.pow base raised to exponent.
Num.sin The sine of an angle in radians.
Num.cos The cosine of an angle in radians.
Num.tan The tangent of an angle in radians.
Num.atan The arctangent, in radians.
Num.add_checked The sum, or :Err(:Overflow); a NaN sum such as Inf + -Inf is :Err(:Undefined).
Num.sub_checked The difference, or :Err(:Overflow).
Num.mul_checked The product, or :Err(:Overflow); a finite double that would become infinite overflows too.
Num.add_saturated Adds two numbers, clamping an integer result to the largest or smallest integer.
Num.sub_saturated Subtracts second from first, clamping an integer result.
Num.mul_saturated Multiplies two numbers, clamping an integer result.
Num.add_wrap Adds two integers, wrapping around on overflow as two’s complement arithmetic does.
Num.sub_wrap Subtracts second from first, wrapping around on overflow.
Num.mul_wrap Multiplies two integers, wrapping around on overflow.
Num.div_checked The quotient as a double, or :Err(:DivByZero).
Num.div_trunc_checked The quotient rounded toward zero, or :Err(:DivByZero); Inf divided by Inf is :Err(:Undefined).
Num.div_ceil_checked Divides and rounds up, or :Err(:DivByZero).
Num.rem_checked The remainder of the truncated division, with the sign of first, or :Err(:DivByZero).
Num.sqrt_checked The square root, or :Err(:SqrtOfNegative).
Num.log_checked The natural logarithm, or :Err(:LogNeedsPositive).
Num.from_r Converts an R number into a ry number, refusing NA and a length other than one: a double becomes an F64 and an integer an I64.
Num.to_r Converts a ry number into an R number: an F64 becomes a double, and an I64 an integer when it fits in 32 bits and a double otherwise.
Num.to_f64 The number as an F64.
Num.to_i64_checked The number as an I64, or :Err(:OutOfBounds) when an I64 cannot hold it exactly, such as a number with a fraction.
Num.to_i64 The number as an I64.
Num.add The sum.
Num.sub second subtracted from first.
Num.mul The product.
Num.div The quotient as a double.
Num.div_trunc The quotient rounded toward zero.
Num.div_ceil The quotient rounded up.
Num.rem The remainder of the truncated division, with the sign of first.
Num.pow_int base raised to a non-negative exponent, as an integer.
Num.sqrt The square root.
Num.log The natural logarithm.
Num.exp The number e raised to number: the exponential function, which is the inverse of Num.log.
Num.asin The arcsine in radians.
Num.acos The arccosine in radians.
Num.is_nan Whether the number is NaN.
Num.bitwise_and The bits set in both integers.
Num.bitwise_or The bits set in either integer.
Num.bitwise_xor The bits set in exactly one of the integers.
Num.bitwise_not The integer with every bit flipped, which is -number - 1.
Num.shift_left_by Shifts the bits left by bits, from 0 to 63 for an I64 and from 0 to 31 for an R number.
Num.shift_right_by Shifts the bits right by bits, copying the sign bit in, so a negative number stays negative.
Num.shift_right_zf_by Shifts the bits right by bits, filling with zeros.
Num.count_one_bits The number of set bits.
Num.count_leading_zero_bits The number of zero bits above the highest set bit, 32 for zero.
Num.count_trailing_zero_bits The number of zero bits below the lowest set bit, 32 for zero.
Num.pi The ratio of a circle’s circumference to its diameter.
Num.tau The ratio of a circle’s circumference to its radius, 2 * Num.pi.
Num.e Euler’s number, the base of the natural logarithm.
Num.max_i64 The largest I64, 9223372036854775807i64.
Num.min_i64 The smallest I64, -9223372036854775808i64.
Num.max_f64 The largest finite double.
Num.min_f64 The most negative finite double, the negation of Num.max_f64.
Num.infinity_f64 Positive infinity, R’s Inf.
Num.nan_f64 Not a number, the F64 that arithmetic such as 0 / 0 produces.
Num.to_str <- function<T: number>(number: T) -> Str

The number as text, with up to 15 significant digits.

Num.to_str(1 / 3)
#> "0.333333333333333"

Source

Num.compare <- function<T: number>(first: T, second: T) -> :LT | :EQ | :GT

:LT, :EQ or :GT, comparing first with second.

Num.compare(2, 1)
#> :GT

Source

Num.min <- function<T: number>(first: T, second: T) -> T

The smaller number.

Num.min(2, 1)
#> 1i64

Source

Num.max <- function<T: number>(first: T, second: T) -> T

The larger number.

Num.max(2.5, 1)
#> 2.5

Source

Num.is_lt <- function<T: number>(first: T, second: T) -> Bool

Whether first < second.

Num.is_lt(1, 2)
#> TRUE

Source

Num.is_gt <- function<T: number>(first: T, second: T) -> Bool

Whether first > second.

Num.is_gt(1, 2)
#> FALSE

Source

Num.is_lte <- function<T: number>(first: T, second: T) -> Bool

Whether first <= second.

Num.is_lte(2, 2)
#> TRUE

Source

Num.is_gte <- function<T: number>(first: T, second: T) -> Bool

Whether first >= second.

Num.is_gte(1.5, 2)
#> FALSE

Source

#: fn(first: F64, second: F64, [rtol]: F64, [atol]: F64) -> Bool
Num.is_approx_eq <- function(first, second, rtol, atol)

Whether two numbers are equal within a relative tolerance rtol (default 1e-5) or an absolute tolerance atol (default 1e-8).

Num.is_approx_eq(0.1 + 0.2, 0.3)
#> TRUE

Source

Num.is_zero <- function<T: number>(number: T) -> Bool

Whether the number is zero.

Num.is_zero(-0)
#> TRUE

Source

Num.is_positive <- function<T: number>(number: T) -> Bool

Whether the number is greater than zero.

Num.is_positive(0)
#> FALSE

Source

Num.is_negative <- function<T: number>(number: T) -> Bool

Whether the number is less than zero.

Num.is_negative(-1)
#> TRUE

Source

Num.is_even <- function(number: I64) -> Bool

Whether the number is a whole, even number.

Num.is_even(4)
#> TRUE

Source

Num.is_odd <- function(number: I64) -> Bool

Whether the number is a whole, odd number.

Num.is_odd(-3)
#> TRUE

Source

Num.is_multiple_of <- function(first: I64, second: I64) -> Bool

Whether first is a whole multiple of second. Only zero is a multiple of zero.

Num.is_multiple_of(12, 4)
#> TRUE

Source

Num.is_finite <- function(number: F64) -> Bool

Whether the number is neither infinite nor NaN.

Num.is_finite(1 / 0)
#> FALSE

Source

Num.is_infinite <- function(number: F64) -> Bool

Whether the number is Inf or -Inf.

Num.is_infinite(-1 / 0)
#> TRUE

Source

Num.abs <- function<T: number>(number: T) -> T

The absolute value.

Num.abs(-3)
#> 3i64

Source

Num.abs_diff <- function<T: number>(first: T, second: T) -> T

The absolute difference of two numbers. An integer result that overflows is an error.

Num.abs_diff(3, 10)
#> 7i64

Source

Num.neg <- function<T: number>(number: T) -> T

The number with its sign flipped.

Num.neg(2.5)
#> -2.5

Source

Num.ceiling <- function(number: F64) -> I64

Rounds up to a whole number, keeping the number type.

Num.ceiling(1.2)
#> 2i64

Source

Num.floor <- function(number: F64) -> I64

Rounds down to a whole number, as an I64.

Num.floor(-1.2)
#> -2i64

Source

Num.round <- function(number: F64) -> I64

Rounds to the nearest whole number, halves away from zero, as an I64.

Num.round(2.5)
#> 3i64

Source

Num.truncate <- function(number: F64) -> I64

Drops the fraction, rounding toward zero, as an I64.

Num.truncate(-1.7)
#> -1i64

Source

Num.pow <- function<T: number>(base: T, exponent: T) -> T

base raised to exponent. A result that is not a real number, as for Num.pow(-1, 0.5), is an error.

Num.pow(2, 10)
#> 1024i64

Source

Num.sin <- function(number: F64) -> F64

The sine of an angle in radians. An infinite angle is an error, because its sine is undefined; the same holds for Num.cos and Num.tan.

Num.sin(0)
#> 0

Source

Num.cos <- function(number: F64) -> F64

The cosine of an angle in radians.

Num.cos(0)
#> 1

Source

Num.tan <- function(number: F64) -> F64

The tangent of an angle in radians.

Num.tan(0)
#> 0

Source

Num.atan <- function(number: F64) -> F64

The arctangent, in radians.

Num.atan(1) * 4
#> 3.14159265358979

Source

Num.add_checked <- function<T: number>(first: T, second: T) -> Result<T, :Overflow | :Undefined>

The sum, or :Err(:Overflow); a NaN sum such as Inf + -Inf is :Err(:Undefined).

Num.add_checked(9223372036854775807i64, 1i64)
#> :Err(:Overflow)

Source

Num.sub_checked <- function<T: number>(first: T, second: T) -> Result<T, :Overflow | :Undefined>

The difference, or :Err(:Overflow).

Num.sub_checked(10, 3)
#> :Ok(7i64)

Source

Num.mul_checked <- function<T: number>(first: T, second: T) -> Result<T, :Overflow | :Undefined>

The product, or :Err(:Overflow); a finite double that would become infinite overflows too.

Num.mul_checked(1e308, 10)
#> :Err(:Overflow)

Source

Num.add_saturated <- function<T: number>(first: T, second: T) -> T

Adds two numbers, clamping an integer result to the largest or smallest integer.

Num.add_saturated(9223372036854775807i64, 1i64)
#> 9223372036854775807i64

Source

Num.sub_saturated <- function<T: number>(first: T, second: T) -> T

Subtracts second from first, clamping an integer result.

Num.sub_saturated(-9223372036854775807i64, 2i64)
#> -9223372036854775808i64

Source

Num.mul_saturated <- function<T: number>(first: T, second: T) -> T

Multiplies two numbers, clamping an integer result.

Num.mul_saturated(4294967296i64, 4294967296i64)
#> 9223372036854775807i64

Source

Num.add_wrap <- function(first: I64, second: I64) -> I64

Adds two integers, wrapping around on overflow as two’s complement arithmetic does.

Num.add_wrap(9223372036854775807i64, 1i64)
#> -9223372036854775808i64

Source

Num.sub_wrap <- function(first: I64, second: I64) -> I64

Subtracts second from first, wrapping around on overflow.

Num.sub_wrap(-9223372036854775808i64, 1i64)
#> 9223372036854775807i64

Source

Num.mul_wrap <- function(first: I64, second: I64) -> I64

Multiplies two integers, wrapping around on overflow.

Num.mul_wrap(4294967296i64, 4294967296i64)
#> 0i64

Source

Num.div_checked <- function(first: F64, second: F64) -> Result<F64, :DivByZero | :Undefined>

The quotient as a double, or :Err(:DivByZero).

Num.div_checked(7, 2)
#> :Ok(3.5)

Source

Num.div_trunc_checked <- function(first: I64, second: I64) -> Result<I64, :DivByZero | :Undefined>

The quotient rounded toward zero, or :Err(:DivByZero); Inf divided by Inf is :Err(:Undefined).

Num.div_trunc_checked(-7, 2)
#> :Ok(-3i64)
Num.div_trunc_checked(Inf, Inf)
#> :Err(:Undefined)

Source

Num.div_ceil_checked <- function(first: I64, second: I64) -> Result<I64, :DivByZero | :Undefined>

Divides and rounds up, or :Err(:DivByZero).

Num.div_ceil_checked(7, 2)
#> :Ok(4i64)

Source

Num.rem_checked <- function(first: I64, second: I64) -> Result<I64, :DivByZero | :Undefined>

The remainder of the truncated division, with the sign of first, or :Err(:DivByZero).

Num.rem_checked(-7, 2)
#> :Ok(-1i64)

Source

Num.sqrt_checked <- function(number: F64) -> Result<F64, :SqrtOfNegative>

The square root, or :Err(:SqrtOfNegative).

Num.sqrt_checked(-1)
#> :Err(:SqrtOfNegative)

Source

Num.log_checked <- function(number: F64) -> Result<F64, :LogNeedsPositive>

The natural logarithm, or :Err(:LogNeedsPositive).

Num.log_checked(exp(2))
#> :Ok(2)

Source

Num.from_r <- function(value: integer) -> I64
Num.from_r <- function(value: double) -> F64

Converts an R number into a ry number, refusing NA and a length other than one: a double becomes an F64 and an integer an I64.

Num.from_r(2.5)
#> 2.5

Source

Num.to_r <- function<T: number>(number: T) -> integer | double

Converts a ry number into an R number: an F64 becomes a double, and an I64 an integer when it fits in 32 bits and a double otherwise. An F64 already passes to R code as a double without this call.

Num.to_r(5i64)
#> 5L

Source

Num.to_f64 <- function<T: number>(number: T) -> F64

The number as an F64. An integer past 2^53 rounds to the nearest F64.

Num.to_f64(3i64)
#> 3

Source

Num.to_i64_checked <- function<T: number>(number: T) -> Result<I64, :OutOfBounds>

The number as an I64, or :Err(:OutOfBounds) when an I64 cannot hold it exactly, such as a number with a fraction. Num.truncate drops a fraction first.

Num.to_i64_checked(-3.7)
#> :Err(:OutOfBounds)

Source

Num.to_i64 <- function<T: number>(number: T) -> I64

The number as an I64. A number an I64 cannot hold exactly is an error; Num.to_i64_checked returns :Err(:OutOfBounds) instead.

Num.to_i64(-3.0)
#> -3i64

Source

Num.add <- function<T: number>(first: T, second: T) -> T

The sum. An integer sum that overflows stops with an error, so use Num.add_checked when overflow is possible. Unlike +, it can be passed by name.

List.walk([1, 2, 3], 0, Num.add)
#> 6i64

Source

Num.sub <- function<T: number>(first: T, second: T) -> T

second subtracted from first. An integer result that overflows is an error, and so is a NaN result such as Inf - Inf.

Num.sub(10, 4)
#> 6i64

Source

Num.mul <- function<T: number>(first: T, second: T) -> T

The product. An integer product that overflows is an error.

Num.mul(6, 7)
#> 42i64

Source

Num.div <- function(first: F64, second: F64) -> F64

The quotient as a double. A zero divisor is an error; Num.div_checked returns :Err(:DivByZero) instead.

Num.div(7, 2)
#> 3.5

Source

Num.div_trunc <- function(first: I64, second: I64) -> I64

The quotient rounded toward zero. A zero divisor is an error.

Num.div_trunc(-7, 2)
#> -3i64

Source

Num.div_ceil <- function(first: I64, second: I64) -> I64

The quotient rounded up. A zero divisor is an error.

Num.div_ceil(7, 2)
#> 4i64

Source

Num.rem <- function(first: I64, second: I64) -> I64

The remainder of the truncated division, with the sign of first. A zero divisor is an error.

Num.rem(-7, 2)
#> -1i64

Source

Num.pow_int <- function(base: I64, exponent: I64) -> I64

base raised to a non-negative exponent, as an integer. A result that overflows is an error; Num.pow returns a double instead.

Num.pow_int(3, 4)
#> 81i64

Source

Num.sqrt <- function(number: F64) -> F64

The square root. A negative number is an error; Num.sqrt_checked returns :Err(:SqrtOfNegative) instead.

Num.sqrt(16)
#> 4

Source

Num.log <- function(number: F64) -> F64

The natural logarithm. A number that is not positive is an error; Num.log_checked returns :Err(:LogNeedsPositive) instead.

Num.log(Num.e)
#> 1

Source

Num.exp <- function(number: F64) -> F64

The number e raised to number: the exponential function, which is the inverse of Num.log.

Num.exp(0)
#> 1

Source

Num.asin <- function(number: F64) -> F64

The arcsine in radians. A number outside -1 to 1 is an error.

Num.asin(1)
#> 1.5707963267949

Source

Num.acos <- function(number: F64) -> F64

The arccosine in radians. A number outside -1 to 1 is an error.

Num.acos(1)
#> 0

Source

Num.is_nan <- function(number: F64) -> Bool

Whether the number is NaN. It is the one library function that accepts NaN; NA is still an error.

Num.is_nan(0 / 0)
#> TRUE

Source

Num.bitwise_and <- function(first: I64, second: I64) -> I64

The bits set in both integers.

Num.bitwise_and(12, 10)
#> 8i64

Source

Num.bitwise_or <- function(first: I64, second: I64) -> I64

The bits set in either integer.

Num.bitwise_or(12, 10)
#> 14i64

Source

Num.bitwise_xor <- function(first: I64, second: I64) -> I64

The bits set in exactly one of the integers. On R numbers, a result whose bit pattern is -2147483648 is an error, because R uses that value for NA; the same holds for every bit operation.

Num.bitwise_xor(12, 10)
#> 6i64

Source

Num.bitwise_not <- function(number: I64) -> I64

The integer with every bit flipped, which is -number - 1.

Num.bitwise_not(5)
#> -6i64

Source

Num.shift_left_by <- function(number: I64, bits: I64) -> I64

Shifts the bits left by bits, from 0 to 63 for an I64 and from 0 to 31 for an R number. Bits shifted past the top are lost, as in Roc.

Num.shift_left_by(1, 4)
#> 16i64

Source

Num.shift_right_by <- function(number: I64, bits: I64) -> I64

Shifts the bits right by bits, copying the sign bit in, so a negative number stays negative.

Num.shift_right_by(-16, 2)
#> -4i64

Source

Num.shift_right_zf_by <- function(number: I64, bits: I64) -> I64

Shifts the bits right by bits, filling with zeros.

Num.shift_right_zf_by(-16, 28)
#> 68719476735i64

Source

Num.count_one_bits <- function(number: I64) -> I64

The number of set bits.

Num.count_one_bits(255)
#> 8L

Source

Num.count_leading_zero_bits <- function(number: I64) -> I64

The number of zero bits above the highest set bit, 32 for zero.

Num.count_leading_zero_bits(1)
#> 31L

Source

Num.count_trailing_zero_bits <- function(number: I64) -> I64

The number of zero bits below the lowest set bit, 32 for zero.

Num.count_trailing_zero_bits(8)
#> 3L

Source

#: F64
Num.pi

The ratio of a circle’s circumference to its diameter. It is a value, not a function.

Num.pi
#> 3.14159265358979

Source

#: F64
Num.tau

The ratio of a circle’s circumference to its radius, 2 * Num.pi.

Num.tau
#> 6.28318530717959

Source

#: F64
Num.e

Euler’s number, the base of the natural logarithm.

Num.e
#> 2.71828182845905

Source

#: I64
Num.max_i64

The largest I64, 9223372036854775807i64. It is a value, not a function.

Num.max_i64
#> 9223372036854775807i64

Source

#: I64
Num.min_i64

The smallest I64, -9223372036854775808i64. It is a value, not a function.

Num.min_i64
#> -9223372036854775808i64

Source

#: F64
Num.max_f64

The largest finite double.

Num.max_f64
#> 1.79769313486232e+308

Source

#: F64
Num.min_f64

The most negative finite double, the negation of Num.max_f64.

Num.min_f64
#> -1.79769313486232e+308

Source

#: F64
Num.infinity_f64

Positive infinity, R’s Inf.

c(Num.infinity_f64, -Num.infinity_f64)
#> c(Inf, -Inf)

Source

#: F64
Num.nan_f64

Not a number, the F64 that arithmetic such as 0 / 0 produces. It is not R’s NA.

Source