Arbitrary-precision integers, rational, floating-point and complex numbers based on GMP, MPFR and MPC
Homepage Repository Cargo Python Documentation Download
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.
Float
and Complex
numbers,
and converting them to strings, now avoids outputting an exponent
term if the radix point can be moved to the correct place without
inserting any extra digits. For example "42.0"
will be produced
rather than "4.20e1"
(issue 18). This change does not affect
output when LowerExp
("{:e}"
format) or UpperExp
("{:E}"
format) is used.The output of Float
and Complex
numbers was
changed as specified above.
Details on other releases can be found in RELEASES.md.
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
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.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
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.
Rug is available on crates.io. To use Rug in your crate, add it as a dependency inside Cargo.toml:
[dependencies]
rug = "1.9"
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:
[dependencies.rug]
version = "1.9"
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.