gossamer/big_int
Arbitrary-precision integer arithmetic for values outside Gleam
Int’s safe-integer range. Construct via from_int
for safe-range starting values or parse when reading
larger literals from text. Mirrors gleam/int where the operation
carries over.
Types
Values
pub fn as_int_n(x: BigInt, bits bits: Int) -> BigIntWraps x to a bits-wide two’s-complement signed integer — x
modulo 2^bits, interpreted as signed. A bits of 0 or less
yields 0. Equivalent to JavaScript’s BigInt.asIntN.
pub fn as_uint_n(x: BigInt, bits bits: Int) -> BigIntWraps x to a bits-wide unsigned integer — x modulo 2^bits. A
bits of 0 or less yields 0. Equivalent to JavaScript’s
BigInt.asUintN.
pub fn base_parse(
string: String,
base: Int,
) -> Result(BigInt, Nil)Parses an integer string in the given base (2–36), with an
optional sign. Digits above 9 use letters, case-insensitively.
Returns Error(Nil) if base is outside that range or the string
isn’t a valid integer in that base.
pub fn bitwise_and(x: BigInt, y: BigInt) -> BigIntReturns the bitwise AND of x and y. Operates on the two’s
complement representation.
pub fn bitwise_exclusive_or(x: BigInt, y: BigInt) -> BigIntReturns the bitwise XOR of x and y. Operates on the two’s
complement representation.
pub fn bitwise_or(x: BigInt, y: BigInt) -> BigIntReturns the bitwise OR of x and y. Operates on the two’s
complement representation.
pub fn bitwise_shift_left(
x: BigInt,
y: BigInt,
) -> Result(BigInt, Nil)Shifts x left by y bits. Returns Error(Nil) if y is
negative, or if the result would exceed the runtime’s BigInt
size limit.
pub fn bitwise_shift_right(
x: BigInt,
y: BigInt,
) -> Result(BigInt, Nil)Shifts x right by y bits (arithmetic shift — sign-extends).
Returns Error(Nil) if y is negative.
pub fn clamp(
x: BigInt,
min min_bound: BigInt,
max max_bound: BigInt,
) -> BigIntRestricts x to be within the range min_bound–max_bound
(inclusive).
pub fn compare(a: BigInt, with b: BigInt) -> order.OrderCompares a and b, returning their relative ordering as a
gleam/order.Order.
pub fn divide(
dividend: BigInt,
by divisor: BigInt,
) -> Result(BigInt, Nil)Truncating integer division. Returns Error(Nil) if divisor is
0.
pub fn floor_divide(
dividend: BigInt,
by divisor: BigInt,
) -> Result(BigInt, Nil)Floored integer division — the quotient is rounded toward negative
infinity. Returns Error(Nil) if divisor is 0.
pub fn from_int(value: Int) -> BigIntCreates a BigInt from a Gleam Int. Pair with parse
when the source is a string literal outside the safe-integer range.
pub fn modulo(
dividend: BigInt,
by divisor: BigInt,
) -> Result(BigInt, Nil)Floored modulo of dividend by divisor — the result takes the
sign of divisor. Returns Error(Nil) if divisor is 0.
pub fn parse(string: String) -> Result(BigInt, Nil)Parses an integer string. Accepts decimal ("42"), hex ("0x2a"),
octal ("0o52"), and binary ("0b101010") literals with an
optional sign and surrounding whitespace. Returns Error(Nil) on
malformed input — decimal floats like "1.5", scientific notation
like "1e3", and the trailing-n literal suffix like "42n" are
all rejected. The empty string parses as 0.
pub fn power(
base: BigInt,
of exponent: BigInt,
) -> Result(BigInt, Nil)Raises base to the power of exponent. Returns Error(Nil) if
exponent is negative (the result would be fractional), or if the
result would exceed the runtime’s BigInt size limit.
pub fn product(numbers: List(BigInt)) -> BigIntMultiplies a list of BigInts. The empty list has a product of 1.
pub fn remainder(
dividend: BigInt,
by divisor: BigInt,
) -> Result(BigInt, Nil)Returns the remainder of dividend / divisor, truncating toward
zero — the result takes the sign of dividend. Returns Error(Nil)
if divisor is 0.
pub fn to_base16(x: BigInt) -> StringReturns the base-16 (hexadecimal) string representation of x, with
uppercase digits.
pub fn to_base2(x: BigInt) -> StringReturns the base-2 (binary) string representation of x.
pub fn to_base36(x: BigInt) -> StringReturns the base-36 string representation of x, with uppercase
digits.
pub fn to_base8(x: BigInt) -> StringReturns the base-8 (octal) string representation of x.
pub fn to_base_string(
x: BigInt,
base: Int,
) -> Result(String, Nil)Returns the string representation of x in the given base
(2–36), with digits above 9 as uppercase letters. Returns
Error(Nil) if base is outside that range.
pub fn to_float(x: BigInt) -> Result(Float, Nil)Converts a BigInt to a Float. Values beyond 2^53 lose
precision; values too large for a Float return Error(Nil) rather
than a non-finite result.
pub fn to_int(x: BigInt) -> Result(Int, Nil)Converts a BigInt to a Gleam Int. Returns Error(Nil) if the
value is outside the safe-integer range (±2^53−1) and would lose
precision when narrowed.