bigfloat

bigfloat is a safe, production‑ready Rust wrapper around the GNU MPFR library for arbitrary‑precision floating‑point arithmetic.

All basic arithmetic is available through operator overloading, and many mathematical functions (sqrt, sin, log, factorial, constants, etc.) are exposed as free functions. Precision can be specified either by the number of bits or by the desired number of decimal digits.

✨ Features

• Arbitrary precision – choose as many bits or decimal digits as you need.
• Operator overloading – &x + &y, &x - &y, &x * &y, &x / &y.
• Rich math functions – roots, powers, logs, trig, inverse trig, factorial, and more.
• Constants – π, e to any desired precision.
• Flexible input – functions accept both string literals and f64.
• Safe Rust interface – MPFR resources are managed automatically (no manual mpfr_clear calls).
• Fast factorial – uses MPFR’s gamma function; can compute (1e6)! in milliseconds.

🚀 Quick Start

Add this to your Cargo.toml:

[dependencies]
bigfloat = "0.0.0"

Basic arithmetic with operators

use bigfloat::*;

let x = "123.456".to_bigfloat(256);
let y = "789.012".to_bigfloat(256);
let sum = &x + &y;

assert_eq!(sum.to_string(10), "912.468");

Using the free functions (default 500 decimal digits)

use bigfloat::*;

// Constants
println!("π = {}", const_pi(Some(50)));
println!("e = {}", const_e(Some(50)));

// Elementary functions
println!("√2 = {}", sqrt(2.0, Some(50)));
println!("ln(5) = {}", ln(5.0, Some(50)));
println!("10^3 = {}", pow(10.0, 3.0, Some(50)));

// Trigonometry
println!("sin(1) = {}", sin(1.0, Some(50)));
println!("cos(1) = {}", cos(1.0, Some(50)));

// Factorial – even huge arguments are fast!
println!("1000! = {}", factorial(1000.0, Some(100)));

📚 API Reference

The BigFloat struct

Free functions (all accept Option<u32> for decimal digits; default 500)

Constants

• const_pi(digits) – π (pi)
• const_e(digits) – e (Euler’s number)

Arithmetic

• add(a, b, digits) / sub(a, b, digits) / mul(a, b, digits) / div(a, b, digits)
• pow(base, exp, digits) – base^exp
• root(b, n, digits) – b^(1/n)
• sqrt(n, digits)

Logarithms

• ln(n, digits) – natural log
• log2(n, digits) – base‑2 log
• log(n, digits) – base‑10 log

Trigonometry

• sin, cos, tan – radians
• asin, acos, atan – inverse trig
• rad_to_deg, deg_to_rad

Factorial

• factorial(n, digits) – n! computed via Γ(n+1)
• ln_factorial(n, digits) – ln(n!)

The MpfrInput trait

pub trait MpfrInput {
    fn to_bigfloat(&self, bits: u64) -> BigFloat;
    fn to_bigfloat_digits(&self, digits: u32) -> BigFloat;
}

Implemented for &str and f64 – so you can pass both string literals and native floats to the free functions.

🔧 Building from Source

Prerequisites

The crate links to native GMP and MPFR libraries via gmp-mpfr-sys.

Arch Linux:

sudo pacman -S mpfr gmp

Debian / Ubuntu:

sudo apt-get install libmpfr-dev libgmp-dev

macOS (Homebrew):

brew install mpfr gmp

Windows (via MSYS2):

pacman -S mingw-w64-x86_64-mpfr mingw-w64-x86_64-gmp

Then, as usual:

cargo build
cargo test

License and AI Training

This project is licensed under the GNU General Public License v3.0 (GPLv3).

The authors of this software consider the use of this code, including its source code, documentation, and any other project artifacts, for the training of artificial intelligence (AI) systems (including but not limited to machine learning, large language models, and other AI technologies) to be creating a derivative work. As such, any entity using this code for such purposes must comply with the terms of the GPLv3. This includes, but is not limited to, making the entire source code of the AI system that uses this code available under the same GPLv3 license.

If you wish to use this code for AI training without being subject to the GPLv3, please contact the authors to negotiate a separate license.