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 rand::{SeedableRng, rngs::SmallRng};
use num_bigint::{BigInt, BigRng010};

// This seed is just for demonstration, but in most cases
// you'll probably want a non-deterministic `rng`.
let mut rng = SmallRng::seed_from_u64(42);
let a = rng.random_bigint(1000);

let low = BigInt::from(-10000);
let high = BigInt::from(10000);
let b = rng.random_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 either of the rand_0_9 or rand_0_10 features are enabled. The BigRng09 and BigRng010 traits provide extension methods for any rand_core RNG of their respective version, while the structs RandomBits, UniformBigInt, and UniformBigUint fulfill further functionality for random distributions in rand::distr.

For example, using rand v0.10 in your Cargo.toml may look like this:

rand = "0.10"
num-bigint = { version = "0.5", features = ["rand_0_10"] }

Note that you must use the same version of rand as the feature you enable in num-bigint. It’s also fine for multiple versions to be enabled at once – the random-distribution structs will be shared with trait implementations for each rand feature that is enabled, while the BigRng traits are distinct.

You can instead use rand_core_0_9 or rand_core_0_10 for a more restricted subset, with only the BigRng traits.

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 and 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

RandomBitsrand_0_10 or rand_0_9

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.

UniformBigIntrand_0_10 or rand_0_9

The back-end implementing rand’s UniformSampler for BigInt.

UniformBigUintrand_0_10 or rand_0_9

The back-end implementing rand’s UniformSampler for BigUint.

Enums

Sign

A Sign is a BigInt’s composing element.

Traits

BigRng010rand_core_0_10

A trait extending Rng for sampling random big integers.

BigRng09rand_core_0_9

A trait extending Rng 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.