API reference
Signatures as the compiler sees them, prose as written beside the code. Generated from the module interface, so nothing here is aspirational.
Integers
Arbitrary-precision integers: core's BigInt, plus the operations and spellings a numeric program needs.
pub fn bit_length(@bigint.BigInt) -> Int32
The number of bits needed to represent n, sign excluded: int.bit_length.
pub fn comb(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt raise Refused
math.comb(n, k): the number of ways to choose k from n without repetition.
pub fn divmod(@bigint.BigInt, @bigint.BigInt) -> (@bigint.BigInt, @bigint.BigInt) raise Refused
divmod(a, b): the floor quotient and the matching remainder.
pub fn factorial(@bigint.BigInt) -> @bigint.BigInt raise Refused
math.factorial(n).
pub fn floor_mod(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt raise Refused
a % b: the remainder that takes the sign of the divisor.
pub fn floordiv(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt raise Refused
a // b: the quotient rounded towards negative infinity.
pub fn gcd(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt
The greatest common divisor, always non-negative.
pub fn isqrt(@bigint.BigInt) -> @bigint.BigInt raise Refused
math.isqrt(n): the floor of the square root.
pub fn lcm(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt
The least common multiple, always non-negative; zero when either side is.
pub fn of_bytes(BytesView, big? : Bool, signed? : Bool) -> @bigint.BigInt
int.from_bytes: the integer held by bytes, big-endian unless big~ = false, two's complement when signed~ = true.
pub fn parse_int(StringView, base? : Int32) -> @bigint.BigInt raise Refused
int(text, base): an integer in any base from 2 to 36, with Python's spelling rules.
Surrounding whitespace is allowed, the sign is optional, digits may be separated by single underscores, and base = 0 means "read the prefix": 0x for hexadecimal, 0o for octal, 0b for binary, decimal otherwise — and, as in Python, leading zeros are then not allowed.
pub fn perm(@bigint.BigInt, @bigint.BigInt) -> @bigint.BigInt raise Refused
math.perm(n, k): the number of ways to choose k from n in order.
pub fn power(@bigint.BigInt, @bigint.BigInt, modulus? : @bigint.BigInt) -> @bigint.BigInt raise Refused
pow(base, exp, modulus), and pow(base, exp) when modulus is absent.
With a modulus and a negative exponent the result is the modular inverse raised to -exp, which is Python's behaviour since 3.8. Without a modulus a negative exponent has no integer answer and is refused.
pub fn to_bytes(@bigint.BigInt, length~ : Int32, big? : Bool, signed? : Bool) -> Bytes raise Refused
int.to_bytes: length bytes holding n, big-endian unless big~ = false.
A signed result is two's complement; an unsigned one refuses negatives.
Floats
Reading, writing and rounding IEEE-754 doubles.
pub fn as_integer_ratio(Double) -> (@bigint.BigInt, @bigint.BigInt) raise Refused
float.as_integer_ratio: the exact numerator and denominator of d.
pub fn as_ratio(Double) -> Fraction raise Refused
d as an exact fraction.
pub fn ceil_big(Double) -> @bigint.BigInt raise Refused
math.ceil(d), as an integer.
pub fn float_hex(Double) -> String
The hexadecimal form of a double: float.hex.
pub fn float_of_hex(StringView) -> Double raise Refused
float.fromhex: the double a hexadecimal literal denotes.
The 0x prefix is optional, the exponent is decimal and introduced by p, and the rounding is the same half-to-even as every other conversion here.
pub fn floor_big(Double) -> @bigint.BigInt raise Refused
math.floor(d), as an integer.
pub fn parse_float(StringView) -> Double raise Refused
float(text): Python's float literal syntax.
Accepts inf, infinity and nan in any case with an optional sign, decimal forms with or without a fractional part or an exponent, single underscores between digits, and surrounding whitespace. Hexadecimal literals are not float syntax; float_of_hex reads those.
pub fn repr_float(Double) -> String
repr(float): the shortest string that reads back as the same double.
pub fn round_big(Double) -> @bigint.BigInt raise Refused
round(d): the nearest integer, ties to even.
pub fn round_float(Double, ndigits~ : Int32) -> Double
round(d, ndigits): round to ndigits decimal places, ties to even, on the exact value of d.
pub fn trunc_big(Double) -> @bigint.BigInt raise Refused
math.trunc(d), as an integer.
Complex numbers
Complex, its arithmetic, and its repr.
pub fn parse_complex(StringView) -> Complex raise Refused
complex(text): 1+2j, (1+2j), j, -j, 1e3j, and 3+5i.
The i suffix is this library's addition; Python only reads j.
pub fn repr_complex(Complex) -> String
repr(z): (1+2j), 2j, (-0-1j), (nan+infj).
pub(all) struct Complex { re : Double
A complex number: z.re + z.im * j.
Adds, subtracts, multiplies, negates and compares with ==; division is Complex::divide because it can refuse a zero divisor.
Implements Add (+) · Default (default()) · Eq (== and !=) · Mul (*) · Neg (unary -) · Show (to_string()) · Sub (-) — the methods they promote are public on Complex.
pub fn Complex::abs(Self) -> Double
abs(z): the Euclidean norm, infinity when either part is infinite.
pub fn Complex::conjugate(Self) -> Self
z.conjugate().
pub fn Complex::divide(Self, Self) -> Self raise Refused
self / other.
A function rather than an operator, for the same reason as Fraction::divide: division by zero has to be reported, and Div cannot.
pub fn Complex::format(Self, StringView) -> String raise Refused
Format a complex number: the real part with the specifier's sign, the imaginary part forced positive, then j, in parentheses unless the real part is a positive zero.
pub fn Complex::j() -> Self
The imaginary unit.
pub fn Complex::new(Double, Double) -> Self
Complex(re, im).
pub fn Complex::pow(Self, Self) -> Self raise Refused
z ** w, including Python's special cases.
An exponent that is a small integer is applied by repeated squaring, as CPython does; anything else goes through the polar form, which is why (1+1j) ** 2 is exactly 2j and (1+1j) ** 2.0 is not.
Fractions
Exact rationals, kept in lowest terms.
pub fn parse_fraction(StringView) -> Fraction raise Refused
Fraction(text): "3/4", "-1.25", "1e-3", "7".
Whitespace is allowed around the sign, the slash and the ends; digits may be separated by single underscores. The decimal and exponent forms are read as exact powers of ten, never through a float.
pub fn repr_fraction(Fraction) -> String
repr(Fraction(3, 4)).
pub(all) struct Fraction { num : @bigint.BigInt
A rational number. den is always positive and gcd(num, den) is always 1, so num and den can be read directly.
Adds, subtracts, multiplies, negates, compares with == and an ordering; division is Fraction::divide because it can refuse a zero divisor.
Implements Add (+) · Compare (<, <=, >, >=) · Default (default()) · Eq (== and !=) · Mul (*) · Neg (unary -) · Show (to_string()) · Sub (-) — the methods they promote are public on Fraction.
pub fn Fraction::abs(Self) -> Self
The same value without its sign.
pub fn Fraction::ceil_big(Self) -> @bigint.BigInt
math.ceil, as an integer.
pub fn Fraction::denominator(Self) -> @bigint.BigInt
The denominator, always positive.
pub fn Fraction::divide(Self, Self) -> Self raise Refused
self / other.
Division is a function and not an operator here: MoonBit's Div trait cannot raise, and a fraction that silently divides by zero or panics would be worse than one that says ZeroDivision.
pub fn Fraction::floor_big(Self) -> @bigint.BigInt
math.floor, as an integer.
pub fn Fraction::floor_divide_big(Self, Self) -> @bigint.BigInt raise Refused
self // other as an integer: Python's floor division of two fractions.
pub fn Fraction::format(Self, StringView) -> String raise Refused
Format a fraction. Without a presentation type it is a ratio, with a digit grouping separator allowed in both halves; with a float type it is the exact rational rounded to the requested digits.
pub fn Fraction::is_integer(Self) -> Bool
Whether the value is a whole number.
pub fn Fraction::limit_denominator(Self, max~ : @bigint.BigInt) -> Self raise Refused
The closest fraction whose denominator is at most max.
pub fn Fraction::modulo(Self, Self) -> Self raise Refused
self % other: the remainder that takes the sign of the divisor.
pub fn Fraction::new(@bigint.BigInt, @bigint.BigInt) -> Self raise Refused
Fraction(num, den).
pub fn Fraction::numerator(Self) -> @bigint.BigInt
The numerator, with the sign.
pub fn Fraction::of_float(Double) -> Self raise Refused
The exact value of a float, as a fraction. 0.1 is not 1/10 here; it is 3602879701896397/36028797018963968, which is what the double holds.
pub fn Fraction::of_int(@bigint.BigInt) -> Self
The integer n as a fraction.
pub fn Fraction::pow(Self, @bigint.BigInt) -> Self raise Refused
self ** exp for an integer exponent.
The exponent is applied to the numerator and the denominator separately, so (2/3) ** 100 is one exact ratio and not a double that nearly is. A negative exponent reciprocates, which is why 0 ** -1 is ZeroDivision and 0 ** 0 is 1, as in Python.
pub fn Fraction::reciprocal(Self) -> Self raise Refused
1/self.
pub fn Fraction::round(Self, ndigits~ : Int32) -> Self
round(self, ndigits): round to ndigits decimal places, ties to even.
pub fn Fraction::round_big(Self) -> @bigint.BigInt
round(self): the nearest integer, ties to even.
pub fn Fraction::to_double(Self) -> Double raise Refused
The nearest double, or Overflow when the value does not fit.
Numbers
The tower: one value that can be any of the four kinds.
pub fn parse(StringView) -> Number raise Refused
parse(text): read a Python number literal and keep the kind it spelled.
A / makes a fraction, a trailing j or i makes a complex number, a point or an exponent or inf/nan makes a float, and anything else is an integer in whatever base its prefix names.
pub(all) enum Number { Int(@bigint.BigInt)
A number of any kind, as the tower arranges them.
Promotion goes Int → Fraction → Float → Complex. Comparison is exact across the tower: an integer is never rounded to a float to be compared with one.
Implements Add (+) · Eq (== and !=) · Mul (*) · Neg (unary -) · Show (to_string()) · Sub (-) — the methods they promote are public on Number.
pub fn Number::compare_numeric(Self, Self) -> Int32 raise Refused
Compare two real numbers, exactly.
Raises Domain for a NaN operand and for a complex number with a non-zero imaginary part, which Python refuses to order.
pub fn Number::divide(Self, Self) -> Self raise Refused
a / b, with Python's result kinds: two integers divide to a float, a fraction stays exact, and a complex number is complex.
pub fn Number::equal_numeric(Self, Self) -> Bool
a == b, across the tower: 1 == 1.0 == Fraction(1) == 1 + 0j.
pub fn Number::floor_mod(Self, Self) -> Self raise Refused
a % b: the remainder that takes the sign of the divisor.
pub fn Number::floordiv(Self, Self) -> Self raise Refused
a // b.
pub fn Number::pow(Self, Self) -> Self raise Refused
a ** b.
pub fn Number::to_double(Self) -> Double raise Refused
The value as a double, or Overflow when it is infinite or not real.
Formatting
The format-specification mini-language.
pub fn format(Number, StringView) -> String raise Refused
format(value, spec), for any number.
pub fn format_float(Double, StringView) -> String raise Refused
Format a double the way Python's format() does.
pub fn format_int(@bigint.BigInt, StringView) -> String raise Refused
Format an integer, including the float types Python allows on integers by converting them.
Errors
One type, four cases.
pub(all) suberror Refused { Malformed(at~ : Int32, reason~ : String)
Everything this library refuses, in one type.
Malformed carries the offset where the input stopped making sense, in UTF-16 code units — the unit StringView indexes by — so a caller can point at the character instead of at the string.
Implements Show (to_string()) — the method it promotes is public on Refused.