Malachite is an arbitrary-precision arithmetic library for Rust. It achieves high performance in part by using algorithms derived from GMP, FLINT, and MPFR.
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.16"
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.16"
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
, andBitAccess
; - Iterator-producing functions that let you generate values for testing.
- Traits that wrap functions from the standard library, like
- malachite-nz (crates.io,
docs.rs) defines two bignum types,
Natural
s andInteger
s. 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 specifiedRoundingMode
; - Various mathematical functions, like implementations of
FloorSqrt
andGcd
; - Modular arithmetic functions, like implementations of
ModAdd
andModPow
, and of traits for arithmetic modulo a power of 2, likeModPowerOf2Add
andModPowerOf2Pow
; - Various functions for logic and bit manipulation, like
BitAnd
andBitAccess
.
If you need to explicitly include this crate as a dependency of the
malachite
crate, use thenaturals_and_integers
ormalachite-nz
feature. - malachite-q (crates.io,
docs.rs) defines
Rational
s. The functions defined on this type include- All the ones you’d expect, like addition, subtraction, multiplication, and division;
- Functions related to conversion between
Rational
s and other kinds of numbers, including primitive floats; - Functions for Diophantine approximation;
- Functions for expressing
Rational
s in scientific notation.
If you need to explicitly include this crate as a dependency of the
malachite
crate, use therationals
ormalachite-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.
Malachite is developed by Mikhail Hogrefe. Thanks to b4D8, florian1345, konstin, Rowan Hart, YunWon Jeong, Park Joon-Kyu, Antonio Mamić, OliverNChalk, and shekohex for additional contributions.
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.
Blog Posts
- Which denominators does an interval contain?
- Iterators that generate everything, part 2
- Iterators that generate everything, part 1
- Intro
Copyright © 2024 Mikhail Hogrefe