### 27 releases (16 stable)

✓ Uses Rust 2018 edition

1.7.0 | Jan 21, 2020 |
---|---|

1.6.0 | Sep 3, 2019 |

1.5.2 | Jul 26, 2019 |

1.3.0 | Jan 26, 2019 |

0.5.0 | Jun 27, 2017 |

#**4** in Math

**5,493** downloads per month

Used in **25** crates
(23 directly)

**LGPL-3.0+**

1.5MB

**25K**
SLoC

# Arbitrary-precision numbers

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

is a bignum integer with arbitrary precision,`Integer`

is a bignum rational number with arbitrary precision,`Rational`

is a multi-precision floating-point number with correct rounding, and`Float`

is a multi-precision complex number with correct rounding.`Complex`

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.7.0 news (2019-01-21)

- The crate now requires rustc version 1.37.0 or later.
- The

and`RemAssignRound`

traits were added.`RemFromRound` - The

,`Rem`

,`RemAssign`

,`RemFrom`

and`RemAssignRound`

traits were implemented for`RemFromRound`

.`Float` - Arithmetic operations with one

or integer primitive operand and one`Integer`

operand were added.`Rational` - The method
`Integer::div_exact_from`

was added. - The methods
`Integer::gcd_u`

,`Integer::gcd_u_mut`

and`Integer::gcd_u_ref`

were added. - The methods
`Integer::lcm_u`

,`Integer::lcm_u_mut`

and`Integer::lcm_u_ref`

were added. - The methods
`Float::remainder`

,`Float::remainder_mut`

,`Float::remainder_round`

,`Float::remainder_from`

,`Float::remainder_from_round`

and`Float::remainder_ref`

were added.

#### Compatibility note

,`SmallInteger`

,`SmallRational`

and`SmallFloat`

are no longer`SmallComplex`

to avoid the possibility of a data race. References obtained by dereferencing them, for example the`Sync``&Integer`

returned from`SmallInteger::deref`

, are still

and`Send`

.`Sync`

### 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

intialized to zero.`Integer`- To assign values to Rug types, we use the

trait and its method`Assign`

. We do not use the assignment operator`Assign`assign`::`

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

. 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.`12``i32` `+` `5``i32`

## 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

is consumed by the subtraction, and `a`

is an owned
`b`

.`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

and `a`

are not consumed, and `b`

is not the final
value. It still needs to be converted or assigned into an `incomplete`

.
This is covered in more detail in the documentation’s
`Integer`*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.7`"`

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.

## Optional features

The Rug crate has six optional features:

, enabled by default. Required for the`integer`

type and its supporting features.`Integer`

, enabled by default. Required for the`rational`

number type and its supporting features. This feature requires the`Rational`

feature.`integer`

, enabled by default. Required for the`float`

type and its supporting features.`Float`

, enabled by default. Required for the`complex`

number type and its supporting features. This feature requires the`Complex`

feature.`float`

, enabled by default. Required for the`rand`

type and its supporting features. This feature requires the`RandState`

feature.`integer`

, disabled by default. This provides serialization support for the`serde`

,`Integer`

,`Rational`

and`Float`

number types, providing that they are enabled. This feature requires the serde crate.`Complex`

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.7`"`
`default-features ``=` `false`
`features ``=` `[``"`integer`"`, `"`float`"`, `"`rand`"``]`

Here only the

, `integer`

and `float`

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
`rand`

trait and the traits that are in the `Assign`

module are
provided by the crate.`ops`

#### Dependencies

~0.2–3.5MB

~96K SLoC