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,
andComplex] is a multi-precision complex number with correct rounding.Rug is a high-level interface to the following [GNU] libraries:
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.
Integer::assign_bytes_radix_unchecked
was added ([issue 41]).Integer now implements [LowerExp] and [UpperExp] for
convenience by transparently converting the Integer to a
Float ([issue 42]).CompleteRound trait is now implemented for
Float::mul_add_mul_refFloat::mul_sub_mul_refCompleteRound trait is now also implemented for
Details on other releases can be found in [RELEASES.md].
```rust use rug::{Assign, Integer}; let mut int = Integer::new(); asserteq!(int, 0); int.assign(14); asserteq!(int, 14);
let decimal = "98765432109876543210"; int.assign(Integer::parse(decimal).unwrap()); assert!(int > 100000000);
let hex160 = "ffff0000ffff0000ffff0000ffff0000ffff0000"; int.assign(Integer::parseradix(hex160, 16).unwrap()); asserteq!(int.significantbits(), 160); int = (int >> 128) - 1; asserteq!(int, 0xfffeffffu32); ```
[Integer][Integer]::[new][new] creates a new [Integer]
intialized to zero.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.[Integer][Integer]::[parse][parse] and
[Integer][Integer]::[parse_radix][parse_radix].int > 100_000_000.int >> 128.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 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
rust
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
rust
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.
Rug is available on crates.io. To use Rug in your crate, add it as a dependency inside [Cargo.toml]:
toml
[dependencies]
rug = "1.17"
Rug requires rustc version 1.37.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.
The Rug crate has six optional features:
integer, enabled by default. Required for the [Integer] type and its
supporting features.rational, enabled by default. Required for the [Rational] number type
and its supporting features. This feature requires the integer feature.float, enabled by default. Required for the [Float] type and its
supporting features.complex, enabled by default. Required for the [Complex] number type and
its supporting features. This feature requires the float feature.rand, enabled by default. Required for the [RandState] type and its
supporting features. This feature requires the integer feature.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 [serde crate].The first five optional features are enabled by default; to use features selectively, you can add the dependency like this to [Cargo.toml]:
toml
[dependencies.rug]
version = "1.17"
default-features = false
features = ["integer", "float", "rand"]
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.
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.
num-traits, disabled by default. This implements some traits from the
[num-traits crate] and the [num-integer crate].