Arbitrary-precision numbers

Rug provides integers and floating-point numbers with arbitrary precision and correct rounding:

• Integer is a bignum integer with arbitrary precision,
• Rational is a bignum rational number with arbitrary precision,
• Float is a multi-precision floating-point number with correct rounding, and
• Complex is a multi-precision complex number with correct rounding.

Rug is a high-level interface to the following GNU libraries:

• GMP for integers and rational numbers,
• MPFR for floating-point numbers, and
• MPC for complex numbers.

Rug is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the full text of the GNU LGPL and GNU GPL for details.

What’s new

Version 1.26.1 news (2024-09-11)

• Bug fix: implementations of CompleteRound were wrongly using prec_t instead of u32 for CompleteRound::Prec (issue 72).

Version 1.26.0 news (2024-08-30)

• Bug fix: Complete was not implemented but documented for incomplete values produced by the following methods (issue 69):
  • Integer::clamp_ref, Integer::invert_ref, Integer::pow_mod_ref
  • Integer::random_bits, Integer::random_below_ref
• Float::get_significand is now usable in const context.
• The experimental feature nightly-float was added (issue 68).

Other releases

Details on other releases can be found in RELEASES.md.

Quick example

use rug::{Assign, Integer};
let mut int = Integer::new();
assert_eq!(int, 0);
int.assign(14);
assert_eq!(int, 14);

let decimal = "98_765_432_109_876_543_210";
int.assign(Integer::parse(decimal).unwrap());
assert!(int > 100_000_000);

let hex_160 = "ffff0000ffff0000ffff0000ffff0000ffff0000";
int.assign(Integer::parse_radix(hex_160, 16).unwrap());
assert_eq!(int.significant_bits(), 160);
int = (int >> 128) - 1;
assert_eq!(int, 0xfffe_ffff_u32);

• Integer::new creates a new Integer intialized to zero.
• To assign values to Rug types, we use the Assign trait and its method Assign::assign. We do not use the assignment operator = as that would drop the left-hand-side operand and replace it with a right-hand-side operand of the same type, which is not what we want here.
• Arbitrary precision numbers can hold numbers that are too large to fit in a primitive type. To assign such a number to the large types, we use strings rather than primitives; in the example this is done using Integer::parse and Integer::parse_radix.
• We can compare Rug types to primitive types or to other Rug types using the normal comparison operators, for example int > 100_000_000.
• Most arithmetic operations are supported with Rug types and primitive types on either side of the operator, for example int >> 128.

Using with primitive types

With Rust primitive types, arithmetic operators usually operate on two values of the same type, for example 12i32 + 5i32. Unlike primitive types, conversion to and from Rug types can be expensive, so the arithmetic operators are overloaded to work on many combinations of Rug types and primitives. More details are available in the documentation.

Operators

Operators are overloaded to work on Rug types alone or on a combination of Rug types and Rust primitives. When at least one operand is an owned value of a Rug type, the operation will consume that value and return a value of the Rug type. For example

use rug::Integer;
let a = Integer::from(10);
let b = 5 - a;
assert_eq!(b, 5 - 10);

Here a is consumed by the subtraction, and b is an owned Integer.

If on the other hand there are no owned Rug types and there are references instead, the returned value is not the final value, but an incomplete-computation value. For example

use rug::Integer;
let (a, b) = (Integer::from(10), Integer::from(20));
let incomplete = &a - &b;
// This would fail to compile: assert_eq!(incomplete, -10);
let sub = Integer::from(incomplete);
assert_eq!(sub, -10);

Here a and b are not consumed, and incomplete is not the final value. It still needs to be converted or assigned into an Integer. This is covered in more detail in the documentation’s Incomplete-computation values section.

More details on operators are available in the documentation.

Using Rug

Rug is available on crates.io. To use Rug in your crate, add it as a dependency inside Cargo.toml:

[dependencies]
rug = "1.26"

Rug requires rustc version 1.65.0 or later.

Rug also depends on the GMP, MPFR and MPC libraries through the low-level FFI bindings in the gmp-mpfr-sys crate, which needs some setup to build; the gmp-mpfr-sys documentation has some details on usage under GNU/Linux, macOS and Windows.

Optional features

The Rug crate has six optional features:

1. integer, enabled by default. Required for the Integer type and its supporting features.
2. rational, enabled by default. Required for the Rational number type and its supporting features. This feature requires the integer feature.
3. float, enabled by default. Required for the Float type and its supporting features.
4. complex, enabled by default. Required for the Complex number type and its supporting features. This feature requires the float feature.
5. rand, enabled by default. Required for the RandState type and its supporting features. This feature requires the integer feature.
6. std, enabled by default. This is for features that are not possible under no_std, such as methods that return String or the implementation of the Error trait.
7. serde, disabled by default. This provides serialization support for the Integer, Rational, Float and Complex number types, providing that they are enabled. This feature requires the std feature and the serde crate.

The first six optional features are enabled by default; to use features selectively, you can add the dependency like this to Cargo.toml:

[dependencies.rug]
version = "1.26"
default-features = false
features = ["integer", "float", "std"]

Here only the integer, float and rand features are enabled. If none of the features are selected, the gmp-mpfr-sys crate is not required and thus not enabled. In that case, only the Assign trait and the traits that are in the ops module are provided by the crate.

Experimental optional features

It is not considered a breaking change if the following experimental features are removed. The removal of experimental features would however require a minor version bump. Similarly, on a minor version bump, optional dependencies can be updated to an incompatible newer version.

1. num-traits, disabled by default. This implements some traits from the num-traits crate and the num-integer crate. (The plan is to promote this to an optional feature once the num-traits crate and the num-integer crate reach version 1.0.0.)
2. nightly-float, disabled by default. This requires the nightly compiler, and implements some operations with the experimental f16 and f128 primitives. (The plan is to always implement the operations and remove this experimental feature once the primitives are stabilized.)