Struct JsBigInt 

pub struct JsBigInt(/* private fields */);

An ECMAScript BigInt using the same short/heap split as QuickJS.

The representation is private so callers cannot construct a non-normalized heap value that should have been a short BigInt.

Implementations

impl JsBigInt

pub fn same_representation(&self, other: &Self) -> bool

Test the tagged representation identity observed by QuickJS’s raw JSValue equality shortcuts. Heap values must share the same cell; numeric equality alone is deliberately insufficient.

pub const fn zero() -> Self

Construct zero in the short representation.

pub const fn one() -> Self

Construct one in the short representation.

pub fn from_bigint(value: BigInt) -> Result<Self, BigIntError>

Construct and normalize a num_bigint::BigInt.

Errors

Returns BigIntError::BigIntTooLarge when the signed limb representation exceeds the QuickJS allocation limit.

pub fn from_integral_f64(value: f64) -> Option<Self>

Convert an exactly integral finite binary64 value to a BigInt.

This is the Number-only branch of QuickJS’s BigInt constructor. The caller retains responsibility for selecting the distinct non-integer and non-finite JavaScript errors.

pub fn parse_js_string(source: &str) -> Result<Self, BigIntError>

Parse the string form accepted by the ECMAScript BigInt constructor.

Leading and trailing ECMAScript whitespace is ignored. The empty string is zero. Decimal text may have a leading + or -; unsigned 0b, 0o, and 0x prefixes are accepted. Numeric separators and a trailing n are deliberately rejected, as they are not part of StringToBigInt.

Errors

Returns BigIntError::InvalidSyntax for malformed input and an allocation-size error for values beyond the upstream limit.

pub fn parse_radix(source: &str, radix: u32) -> Result<Self, BigIntError>

Parse an optionally signed digit sequence in radix.

Unlike Self::parse_js_string, this low-level entry point does not trim whitespace or recognize a base prefix.

Errors

Returns BigIntError::InvalidRadix, BigIntError::InvalidSyntax, or an allocation-size error.

pub fn to_string_radix(&self, radix: u32) -> Result<String, BigIntError>

Format the integer with lowercase digits in radix.

Errors

Returns BigIntError::InvalidRadix unless radix is in 2..=36.

pub const fn is_short(&self) -> bool

Whether this value uses the JS_TAG_SHORT_BIG_INT-like fast path.

pub const fn as_i64(&self) -> Option<i64>

Return the immediate value, or None for a heap BigInt.

pub fn to_bigint(&self) -> BigInt

Return a cloned arbitrary-precision value for external integrations.

pub fn to_f64(&self) -> f64

Convert this integer to the nearest IEEE-754 binary64 value.

This is the conversion used by the Number constructor’s ToNumeric path. It is deliberately separate from ordinary ToNumber, which must continue to reject BigInt primitives. num-bigint retains sticky lower bits before the final hardware conversion, yielding round-to-nearest, ties-to-even and signed infinity on overflow like pinned QuickJS.

pub fn cmp_f64(&self, number: f64) -> Option<Ordering>

Compare exactly with a Number, as IsLessThan requires (None for NaN).

pub fn magnitude_bits(&self) -> u64

The unsigned magnitude bit length (0 for zero).

pub fn signed_limb_len(&self) -> u64

Number of normalized signed 64-bit limbs used by QuickJS.

pub fn exceeds_allocation_limit(&self) -> bool

pub fn is_zero(&self) -> bool

Whether this value is zero.

pub fn is_negative(&self) -> bool

Whether this value is negative.

pub fn add(&self, rhs: &Self) -> Result<Self, BigIntError>

Add two BigInts, promoting on short overflow and compacting the result.

Errors

Returns BigIntError::BigIntTooLarge if the result exceeds the upstream allocation limit.

pub fn sub(&self, rhs: &Self) -> Result<Self, BigIntError>

Subtract two BigInts, promoting on short overflow and compacting the result.

Errors

Returns BigIntError::BigIntTooLarge if the result exceeds the upstream allocation limit.

pub fn update_decrement(&self) -> Result<Self, BigIntError>

Apply the pinned QuickJS 2026-06-04 BigInt -- operation.

QuickJS handles ordinary short values in its VM fast path. At i64::MIN and for every heap BigInt it enters js_unary_arith_slow, where unsigned opcode-enum arithmetic turns the intended -1 limb into UINT32_MAX before js_bigint_add. This observable release quirk is deliberately confined to update-decrement; binary subtraction keeps mathematical BigInt semantics.

pub fn mul(&self, rhs: &Self) -> Result<Self, BigIntError>

Multiply two BigInts, promoting on short overflow and compacting the result.

Errors

Returns BigIntError::BigIntTooLarge if the result exceeds the upstream allocation limit.

pub fn div(&self, rhs: &Self) -> Result<Self, BigIntError>

Divide with truncation toward zero, as required for ECMAScript BigInt.

Errors

Returns BigIntError::DivisionByZero when rhs is zero.

pub fn rem(&self, rhs: &Self) -> Result<Self, BigIntError>

Compute a remainder whose sign follows the dividend.

Errors

Returns BigIntError::DivisionByZero when rhs is zero.

pub fn pow(&self, exponent: &Self) -> Result<Self, BigIntError>

Raise this value to a non-negative BigInt exponent.

0, 1, and -1 retain the same constant-result shortcuts as js_bigint_pow, even when the exponent itself is too large to fit a machine integer.

Errors

Returns BigIntError::NegativeExponent for a negative exponent, BigIntError::BigIntTooLarge when the mathematical exponent exceeds the upstream limit, and BigIntError::AllocationTooLarge when an intermediate or final allocation crosses the nominal limb guard.

pub fn neg(&self) -> Result<Self, BigIntError>

Arithmetic negation, promoting i64::MIN to a heap BigInt.

Errors

Returns BigIntError::BigIntTooLarge if the result exceeds the upstream allocation limit.

pub fn bit_and(&self, rhs: &Self) -> Result<Self, BigIntError>

Infinite-width two’s-complement bitwise AND.

Errors

Returns BigIntError::AllocationTooLarge when either operand came from QuickJS’s unguarded one-sign-limb extension.

pub fn bit_or(&self, rhs: &Self) -> Result<Self, BigIntError>

Infinite-width two’s-complement bitwise OR.

Errors

Returns BigIntError::AllocationTooLarge when either operand came from QuickJS’s unguarded one-sign-limb extension.

pub fn bit_xor(&self, rhs: &Self) -> Result<Self, BigIntError>

Infinite-width two’s-complement bitwise XOR.

Errors

Returns BigIntError::AllocationTooLarge when either operand came from QuickJS’s unguarded one-sign-limb extension.

pub fn bit_not(&self) -> Result<Self, BigIntError>

Infinite-width two’s-complement bitwise NOT.

Errors

Returns BigIntError::AllocationTooLarge when the operand came from QuickJS’s unguarded one-sign-limb extension.

pub fn shl(&self, count: &Self) -> Result<Self, BigIntError>

ECMAScript BigInt left shift. A negative count shifts right.

Errors

Returns BigIntError::ShiftTooLarge when a non-zero left-shift result would exceed the QuickJS allocation limit.

pub fn shr(&self, count: &Self) -> Result<Self, BigIntError>

ECMAScript BigInt arithmetic right shift. A negative count shifts left.

Errors

Returns BigIntError::ShiftTooLarge when a reversed (left) shift would exceed the QuickJS allocation limit.

pub fn as_int_n(&self, bits: u64) -> Result<Self, BigIntError>

QuickJS 2026-06-04 behavior for BigInt.asIntN(bits, value).

Errors

Returns BigIntError::AllocationTooLarge when truncation would allocate the 16,385th nominal limb. The pinned release still returns an already-extended input unchanged once bits reaches its storage width, so that early return remains deliberately ahead of the guard.

pub fn as_uint_n(&self, bits: u64) -> Result<Self, BigIntError>

QuickJS 2026-06-04 behavior for BigInt.asUintN(bits, value).

This intentionally preserves the upstream signed-limb behavior instead of silently substituting the ECMA-262 result. In this release, a short negative value is returned unchanged for bits >= 64; heap truncation at a multiple of 64 can likewise produce a negative value. These are observable compatibility requirements for the selected baseline.

Errors

Returns BigIntError::AllocationTooLarge at the same guarded truncation boundary as Self::as_int_n.

Trait Implementations

impl Clone for JsBigInt

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JsBigInt

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for JsBigInt

fn default() -> Self

Returns the “default value” for a type.

impl Display for JsBigInt

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for JsBigInt

impl From<i32> for JsBigInt

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for JsBigInt

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i128> for JsBigInt

fn from(value: i128) -> Self

Converts to this type from the input type.

impl From<u32> for JsBigInt

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for JsBigInt

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u128> for JsBigInt

fn from(value: u128) -> Self

Converts to this type from the input type.

impl FromStr for JsBigInt

type Err = BigIntError

The associated error which can be returned from parsing.

fn from_str(source: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for JsBigInt

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for JsBigInt

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for JsBigInt

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for JsBigInt

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralPartialEq for JsBigInt

impl TryFrom<BigInt> for JsBigInt

type Error = BigIntError

The type returned in the event of a conversion error.

fn try_from(value: BigInt) -> Result<Self, Self::Error>

Performs the conversion.