Crate num_bigint

Big Integer Types for Rust

• A BigUint is unsigned and represented as a vector of digits.
• A BigInt is signed and is a combination of BigUint and Sign.

Common numerical operations are overloaded, so we can treat them the same way we treat other numbers.

Example

use num_bigint::BigUint;
use num_traits::One;

// Calculate large fibonacci numbers.
fn fib(n: usize) -> BigUint {
    let mut f0 = BigUint::ZERO;
    let mut f1 = BigUint::one();
    for _ in 0..n {
        let f2 = f0 + &f1;
        f0 = f1;
        f1 = f2;
    }
    f0
}

// This is a very large number.
println!("fib(1000) = {}", fib(1000));

It’s easy to generate large random numbers:

use num_bigint::{ToBigInt, RandBigInt};

let mut rng = rand::thread_rng();
let a = rng.gen_bigint(1000);

let low = -10000.to_bigint().unwrap();
let high = 10000.to_bigint().unwrap();
let b = rng.gen_bigint_range(&low, &high);

// Probably an even larger number.
println!("{}", a * b);

See the “Features” section for instructions for enabling random number generation.

Features

The std crate feature is enabled by default, which enables std::error::Error implementations and some internal use of floating point approximations. This can be disabled by depending on num-bigint with default-features = false. Either way, the alloc crate is always required for heap allocation of the BigInt/BigUint digits.

Random Generation

num-bigint supports the generation of random big integers when the rand feature is enabled. To enable it include rand as

rand = "0.8"
num-bigint = { version = "0.4", features = ["rand"] }

Note that you must use the version of rand that num-bigint is compatible with: 0.8.

Arbitrary Big Integers

num-bigint supports arbitrary and quickcheck features to implement [arbitrary::Arbitrary] and [quickcheck::Arbitrary], respectively, for both BigInt and BigUint. These are useful for fuzzing and other forms of randomized testing.

Serialization

The serde feature adds implementations of [Serialize][serde::Serialize] and [Deserialize][serde::Deserialize] for both BigInt and BigUint. Their serialized data is generated portably, regardless of platform differences like the internal digit size.

Compatibility

The num-bigint crate is tested for rustc 1.60 and greater.

Structs

• BigInt
  A big signed integer type.
• BigUint
  A big unsigned integer type.
• ParseBigIntError
• RandomBits
  A random distribution for BigUint and BigInt values of a particular bit size.
• TryFromBigIntError
  The error type returned when a checked conversion regarding big integer fails.
• U32Digits
  An iterator of u32 digits representation of a BigUint or BigInt, ordered least significant digit first.
• U64Digits
  An iterator of u64 digits representation of a BigUint or BigInt, ordered least significant digit first.
• UniformBigInt
  The back-end implementing rand’s UniformSampler for BigInt.
• UniformBigUint
  The back-end implementing rand’s UniformSampler for BigUint.

Enums

• Sign
  A Sign is a BigInt’s composing element.

Traits

• RandBigInt
  A trait for sampling random big integers.
• ToBigInt
  A generic trait for converting a value to a BigInt. This may return None when converting from f32 or f64, and will always succeed when converting from any integer or unsigned primitive, or BigUint.
• ToBigUint
  A generic trait for converting a value to a BigUint.