Icon LinkBig Integers Library

The Big Integers library provides a library to use extremely large numbers in Sway. It has 1 distinct types: BigUint. These types are heap allocated.

Internally the library uses the Vec<u64> type to represent the underlying values of the big integers.

For implementation details on the Big Integers Library please see the Sway Libs Docs Icon Link.

Icon LinkImporting the Big Integers Library

In order to use the Big Integer Number Library, Sway Libs must be added to the Forc.toml file and then imported into your Sway project. To add Sway Libs as a dependency to the Forc.toml file in your project please see the Getting Started .

To import the Big Integer Number Library to your Sway Smart Contract, add the following to your Sway file:

use sway_libs::bigint::*;

In order to use any of the Big Integer types, import them into your Sway project like so:

use sway_libs::bigint::BigUint;

Icon LinkBasic Functionality

Icon LinkMinimum and Maximum Values

For the BigUint type, the minimum value is zero. There is no maximum value and the BigUint will grow to accommodate as large of a number as needed.

Icon LinkInstantiating a Big Integer

Icon LinkZero value

Once imported, a Big Integer type can be instantiated defining a new variable and calling the new function.

let mut big_int = BigUint::new();

this newly initialized variable represents the value of 0.

The new function is functionally equivalent to the zero function.

let zero = BigUint::zero();

Icon LinkBasic Mathematical Functions

Basic arithmetic operations are working as usual.

let big_uint_1 = BigUint::from(1u64);
let big_uint_2 = BigUint::from(2u64);
 
// Add
let result: BigUint = big_uint_1 + big_uint_2;
 
// Multiply
let result: BigUint = big_uint_1 * big_uint_2;
 
// Subtract
let result: BigUint = big_uint_2 - big_uint_1;
 
// Eq
let result: bool = big_uint_1 == big_uint_2;
 
// Ord
let result: bool = big_uint_1 < big_uint_2;

Icon LinkChecking if a Big Integer is Zero

The library also provides a helper function to easily check if a Big Integer is zero.

fn is_zero() {
    let big_int = BigUint::zero();
    assert(big_int.is_zero());
}

Icon LinkType Conversions

The Big Integers Library offers a number of different conversions between mathematical types. These include the following:

• u8
• u16
• u32
• u64
• U128
• u256
• Bytes

To convert any of the above type to a Big Integer, you may use the From implementation.

// u8
let u8_big_int = BigUint::from(u8::max());
 
// u16
let u16_big_int = BigUint::from(u16::max());
 
// u32
let u32_big_int = BigUint::from(u32::max());
 
// u64
let u64_big_int = BigUint::from(u64::max());
 
// U128
let u128_big_int = BigUint::from(U128::max());
 
// u256
let u256_big_int = BigUint::from(u256::max());
 
// Bytes
let bytes_big_int = BigUint::from(Bytes::new());

To convert back to any of the above types, the TryInto implementation will be needed. If the Bit Integer does not fit into the conversion type, None will be returned.

let big_uint = BigUint::zero();
 
// u8
let u8_result: Option<u8> = <BigUint as TryInto<u8>>::try_into(big_uint);
 
// u16
let u16_result: Option<u16> = <BigUint as TryInto<u16>>::try_into(big_uint);
 
// u32
let u32_result: Option<u32> = <BigUint as TryInto<u32>>::try_into(big_uint);
 
// u64
let u64_result: Option<u64> = <BigUint as TryInto<u64>>::try_into(big_uint);
 
// U128
let u128_big_int: Option<U128> = <BigUint as TryInto<U128>>::try_into(big_uint);
 
// u256
let u256_big_int: Option<u256> = <BigUint as TryInto<u256>>::try_into(big_uint);

The only exception is the Bytes type, which uses Into.

// Bytes
let bytes_big_int: Bytes = <BigUint as Into<Bytes>>::into(big_uint);

Icon LinkUnderlying Values

As mentioned previously, the big integers are internally represented by a Vec<u64>. To introspect these underlying values you may either get a copy of the data, inspect individual elements, or get the length.

To get a copy of the underlying data, you may call the limbs() function. Please note that modifying the copy will have no impact on the Big Integer.

let limbs: Vec<u64> = big_int.limbs();

To introspect an individual element, you may use the get_limb() function.

let limb: Option<u64> = big_int.get_limb(0);

To get the length of the underlying Vec<u64>, call the number_of_limbs() function.

let number_of_limbs: u64 = big_int.number_of_limbs();

And to check whether two Big Integers have the same number of limbs, you may use the equal_limb_size() function.

let result: bool = big_int_1.equal_limb_size(big_int_2);