View on GitHub

malachite

An arbitrary-precision arithmetic library for Rust.

Malachite is an arbitrary-precision arithmetic library for Rust. It achieves high performance in part by using algorithms derived from GMP and FLINT.

use malachite::num::arithmetic::traits::Factorial;
use malachite::Natural;

fn main() {
    println!("{}", Natural::factorial(100));
}

The code above outputs the following:

93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000

You have to scroll to see the entire output.

Here’s a more complex example, calculating the negative-one-millionth power of 3 and displaying the result with 30 digits of precision.

use malachite::num::arithmetic::traits::Pow;
use malachite::num::conversion::string::options::ToSciOptions;
use malachite::num::conversion::traits::ToSci;
use malachite::Rational;

fn main() {
    let mut options = ToSciOptions::default();
    options.set_precision(30);
    println!("{}", Rational::from(3).pow(-1_000_000i64).to_sci_with_options(options));
}

The output is this:

5.56263209915712886588211486263e-477122

Every digit is correct, except that the least-significant digit was rounded up from 2. The default rounding mode, Nearest, uses bankers’ rounding, but you may specify different rounding behavior via the options parameter.

Malachite is designed to work with very large numbers efficiently. See here for a performance comparison against other libraries.

Malachite uses no_std, unless the random, test_build, or bin_build features are enabled.

To use Malachite, add the following to your project’s Cargo.toml file:

[dependencies.malachite]
version = "0.4.7"

By default, all of Malachite’s features are included, but you can opt out of some of them. For example, if you want to use Natural and Integer but not Rational, you can instead use

[dependencies.malachite]
version = "0.4.7"
default-features = false
features = [ "naturals_and_integers" ]

The malachite crate re-exports three sub-crates.

malachite-base (crates.io, docs.rs) is a collection of utilities supporting the other crates. It includes
- Traits that wrap functions from the standard library, like CheckedAdd;
- Traits that give extra functionality to primitive types, like Gcd, FloorSqrt, and BitAccess;
- Iterator-producing functions that let you generate values for testing.
malachite-nz (crates.io, docs.rs) defines two bignum types, Naturals and Integers. The functions defined on these types include
- All the ones you’d expect, like addition, subtraction, multiplication, and integer division;
- Implementations of DivRound, which provides division that rounds according to a specified RoundingMode;
- Various mathematical functions, like implementations of FloorSqrt and Gcd;
- Modular arithmetic functions, like implementations of ModAdd and ModPow, and of traits for arithmetic modulo a power of 2, like ModPowerOf2Add and ModPowerOf2Pow;
- Various functions for logic and bit manipulation, like BitAnd and BitAccess.
If you need to explicitly include this crate as a dependency of the malachite crate, use the naturals_and_integers or malachite-nz feature.
malachite-q (crates.io, docs.rs) defines Rationals. The functions defined on this type include
- All the ones you’d expect, like addition, subtraction, multiplication, and division;
- Functions related to conversion between Rationals and other kinds of numbers, including primitive floats;
- Functions for Diophantine approximation;
- Functions for expressing Rationals in scientific notation.
If you need to explicitly include this crate as a dependency of the malachite crate, use the rationals or malachite-q feature.
malachite-float Arbitrary-precision floating-point numbers. These are in development, and most features are missing.

Malachite is under active development, with many more types and features planned for the future. Nonetheless, it is extensively tested and documented, and ready for use today. Just be aware that its API is not stable yet, and that it is licensed under LGPL 3.0.

FAQ

How is “Malachite” pronounced, and what does it mean? “Malachite” is pronounced MA-luh-kite, or /ˈmæl.əˌkaɪt/. It is the name of a green gemstone. Unfortunately, malachite does not contain iron, which would have made it a particularly good namesake for a Rust library.

Malachite’s logo is an image of a snub cube.

When does Malachite allocate memory? Any Natural less than \(2^{64}\) is represented inline, without allocating memory. Any Integer whose absolute value is less than \(2^{64}\) doesn’t allocate either, and neither does any Rational whose absolute numerator and denominator are both less than \(2^{64}\). If you’re using a build with --features 32_bit_limbs, then the threshold is \(2^{32}\) instead.

Can I build Malachite for WebAssembly? Yes. If, in the future, Malachite includes code incompatible with Wasm (for example, code that uses rayon), it will be possible to disable that code with cargo flags.

FAQ

Blog Posts