Struct JsBigInt

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

Available on crate feature napi-6 only.

The type of JavaScript BigInt values.

Example

The following shows an example of adding two numbers that exceed Number.MAX_SAFE_INTEGER.

fn add_bigint(mut cx: FunctionContext) -> JsResult<JsBigInt> {
    // Get references to the `BigInt` arguments
    let a = cx.argument::<JsBigInt>(0)?;
    let b = cx.argument::<JsBigInt>(1)?;

    // Convert the `BigInt` to `i64`
    let a = a.to_i64(&mut cx)
        // On failure, convert err to a `RangeError` exception
        .or_throw(&mut cx)?;

    let b = b.to_i64(&mut cx).or_throw(&mut cx)?;
    let sum = a + b;

    // Create a `BigInt` from the `i64` sum
    Ok(JsBigInt::from_i64(&mut cx, sum))
}

Implementations

impl JsBigInt

pub const POSITIVE: Sign = Sign::Positive

pub const NEGATIVE: Sign = Sign::Negative

pub fn from_i64<'cx, C>(cx: &mut C, n: i64) -> Handle<'cx, Self>

where C: Context<'cx>,

Creates a BigInt from an i64.

Example

let value: Handle<JsBigInt> = JsBigInt::from_i64(&mut cx, 42);

pub fn from_u64<'cx, C>(cx: &mut C, n: u64) -> Handle<'cx, Self>

where C: Context<'cx>,

Creates a BigInt from a u64.

Example

let value: Handle<JsBigInt> = JsBigInt::from_u64(&mut cx, 42);

pub fn from_i128<'cx, C>(cx: &mut C, n: i128) -> Handle<'cx, Self>

where C: Context<'cx>,

Creates a BigInt from an i128.

Example

let value: Handle<JsBigInt> = JsBigInt::from_i128(&mut cx, 42);

pub fn from_u128<'cx, C>(cx: &mut C, n: u128) -> Handle<'cx, Self>

where C: Context<'cx>,

Creates a BigInt from a u128.

Example

let value: Handle<JsBigInt> = JsBigInt::from_u128(&mut cx, 42);

pub fn from_digits_le<'cx, C>( cx: &mut C, sign: Sign, digits: &[u64], ) -> Handle<'cx, Self>

where C: Context<'cx>,

Creates a BigInt from a signed magnitude. The BigInt is calculated as:
Sign * (digit[0] x (2⁶⁴)⁰ + digit[0] x (2⁶⁴)¹ + digit[0] x (2⁶⁴)² ...)

Example

// Creates a `BigInt` equal to `2n ** 128n`
let value: Handle<JsBigInt> = JsBigInt::from_digits_le(
    &mut cx,
    JsBigInt::POSITIVE,
    &[0, 0, 1],
);

pub fn to_i64<'cx, C>(&self, cx: &mut C) -> Result<i64, RangeError<i64>>

where C: Context<'cx>,

Reads an i64 from a BigInt.

Fails on overflow and underflow.

Example

See JsBigInt.

pub fn to_u64<'cx, C>(&self, cx: &mut C) -> Result<u64, RangeError<u64>>

where C: Context<'cx>,

Reads a u64 from a BigInt.

Fails on overflow or a negative sign.

pub fn to_i128<'cx, C>(&self, cx: &mut C) -> Result<i128, RangeError<i128>>

where C: Context<'cx>,

Reads an i128 from a BigInt.

Fails on overflow and underflow.

pub fn to_u128<'cx, C>(&self, cx: &mut C) -> Result<u128, RangeError<u128>>

where C: Context<'cx>,

Reads a u128 from a BigInt.

Fails on overflow or a negative sign.

pub fn to_digits_le<'cx, C>(&self, cx: &mut C) -> (Sign, Vec<u64>)

where C: Context<'cx>,

Gets a signed magnitude pair from a BigInt.

The BigInt is calculated as:
Sign * (digit[0] x (2⁶⁴)⁰ + digit[0] x (2⁶⁴)¹ + digit[0] x (2⁶⁴)² ...)

pub fn read_digits_le<'cx, C>( &self, cx: &mut C, digits: &mut [u64], ) -> (Sign, usize)

where C: Context<'cx>,

Gets the sign from a BigInt and reads digits into a buffer. The returned usize is the total number of digits in the BigInt.

Example

Read a u256 from a BigInt.

fn bigint_to_u256(cx: &mut FunctionContext, n: Handle<JsBigInt>) -> NeonResult<[u64; 4]> {
    let mut digits = [0; 4];
    let (sign, num_digits) = n.read_digits_le(cx, &mut digits);

    if sign == JsBigInt::NEGATIVE {
        return cx.throw_error("Underflow reading u256 from BigInt");
    }

    if num_digits > digits.len() {
        return cx.throw_error("Overflow reading u256 from BigInt");
    }

    Ok(digits)
}

pub fn len<'cx, C>(&self, cx: &mut C) -> usize

where C: Context<'cx>,

Gets the number of u64 digits in a BigInt

Trait Implementations

impl Debug for JsBigInt

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

Formats the value using the given formatter.

impl Value for JsBigInt

fn to_string<'cx, C: Context<'cx>>(&self, cx: &mut C) -> JsResult<'cx, JsString>

fn as_value<'cx, C: Context<'cx>>(&self, _: &mut C) -> Handle<'cx, JsValue>

fn to_raw(&self) -> Value

Available on crate feature sys only.

Get a raw reference to the wrapped Node-API value.

unsafe fn from_raw<'cx, C: Context<'cx>>( cx: &C, value: Value, ) -> Handle<'cx, Self>

Available on crate feature sys only.

Creates a value from a raw Node-API value.