baml.Bigint

(internal) Number of bytes needed for one draw over [lower, upper).

(internal) Maps one draw onto [lower, upper), returning upper when the draw must be rejected.

Parses text as a base ten signed integer.

Accepts an optional leading + or - followed by one or more ASCII digits, and nothing else: no surrounding whitespace, no underscore separators, no 0x / 0o / 0b prefix, no Unicode digits, no scientific notation. Preprocess the string if you need any of those.

Throws

• baml.errors.ParseError if text is empty or holds a non-digit character.

Examples

bigint.parse("42")       // 42n
bigint.parse("-7")       // -7n
bigint.parse("+0")       // 0n
bigint.parse("")         // throws — empty
bigint.parse("12a")      // throws — non-digit
bigint.parse("0x2a")     // throws — hex prefix not accepted
bigint.parse("1_000")    // throws — underscores not accepted
bigint.parse(" 5 ")      // throws — whitespace; trim first
bigint.parse("99999999999999999999")  // 99999999999999999999n

Returns a uniformly distributed random integer in the half-open range [lower, upper), drawn from rng.

rng defaults to random.SystemRandom, the host's cryptographic entropy source; pass a seeded generator to make the draw reproducible. Rejection sampling avoids modulo bias, so one result may consume several draws from rng.

Throws

• baml.errors.InvalidArgument if lower >= upper, which would leave the range empty.

Examples

bigint.random(0n, 10n)         // some value in {0, 1, ..., 9}
bigint.random(-5n, 5n)         // some value in {-5, -4, ..., 4}
bigint.random(0n, 1n)          // always 0  (single-element range)
bigint.random(5n, 5n)          // throws — empty range
bigint.random(10n, 0n)         // throws — lower > upper

// Reproducible: the same seed replays the same values.
let rng = baml.random.Xoshiro256PlusPlus.new(seed = my_seed);
bigint.random(0n, 10n, rng = rng)

Returns the absolute value of self.

Examples

(-7n).abs()         // 7n
(3n).abs()          // 3n

Returns the largest n such that base ** n <= self: the logarithm of self in base, rounded down.

Throws

• baml.errors.InvalidArgument if self <= 0 or base < 2.

Examples

(1000n).ilog(10n)   // 3n
(1024n).ilog(2n)    // 10n
(1n).ilog(10n)      // 0n
(0n).ilog(10n)      // throws
(10n).ilog(1n)      // throws

Returns the largest r such that r * r <= self: the integer square root of self.

Throws

• baml.errors.InvalidArgument if self is negative.

Examples

(10n).isqrt()   // 3n
(16n).isqrt()   // 4n
(-1n).isqrt()   // throws

Returns self ** exp.

0 ** 0 is 1n, by convention. A negative exp gives 0n, because the exact value 1 / self ** -exp lies in (-1, 1) for |self| > 1 and rounds toward zero. That holds uniformly: for self == 1n or self == -1n the exact value is ±1n, and the result is still 0n.

Panics

• baml.panics.AllocFailure if the estimated result exceeds bigint's workspace cap.

Examples

(2n).pow(10n)      // 1024n
(2n).pow(0n)       // 1n
(0n).pow(0n)       // 1n   (convention)
(2n).pow(-1n)      // 0n
(-2n).pow(3n)      // -8n
(10n).pow(100n)    // a very large number

Narrows self to a fixed-width int.

Throws

• baml.errors.InvalidArgument if self falls outside int's range. BAML integers are 63-bit signed, so int.min_value() through int.max_value() is narrower than a machine 64-bit integer.

Examples

(42n).to_int()                          // 42
(-7n).to_int()                          // -7
(4611686018427387903n).to_int()         // int.max_value()
(4611686018427387904n).to_int()         // throws — one past int.max_value()
(10n).pow(30n).to_int()                 // throws