Struct rug::Float [−] [src]

pub struct Float { /* fields omitted */ }

A multi-precision floating-point number with arbitrarily large precision and correct rounding

The precision has to be set during construction. The rounding method of the required operations can be specified, and the direction of the rounding is returned.

Examples

use rug::Float;
use rug::float::Round;
use rug::ops::DivAssignRound;
use std::cmp::Ordering;
// A precision of 32 significant bits is specified here.
// (The primitive `f32` has a precision of 24 and
// `f64` has a precision of 53.)
let mut two_thirds_down = Float::with_val(32, 2.0);
let dir = two_thirds_down.div_assign_round(3.0, Round::Down);
// since we rounded down, direction is Ordering::Less
assert_eq!(dir, Ordering::Less);
let mut two_thirds_up = Float::with_val(32, 2.0);
let dir = two_thirds_up.div_assign_round(3.0, Round::Up);
// since we rounded up, direction is Ordering::Greater
assert_eq!(dir, Ordering::Greater);
let diff_expected = 2.0_f64.powi(-32);
let diff = two_thirds_up - two_thirds_down;
assert_eq!(diff, diff_expected);

Operations on two borrowed Float numbers result in an incomplete-computation value that has to be assigned to a new Float value.

use rug::Float;
let a = Float::with_val(53, 10.5);
let b = Float::with_val(53, -1.25);
let a_b_ref = &a + &b;
let a_b = Float::with_val(53, a_b_ref);
assert_eq!(a_b, 9.25);

As a special case, when an incomplete-computation value is obtained from multiplying two Float references, it can be added to or subtracted from another Float (or reference). This will result in a fused multiply-accumulate operation, with only one rounding operation taking place.

use rug::Float;
// Use only 4 bits of precision for demonstration purposes.
// 24 in binary is 11000.
let a = Float::with_val(4, 24);
// 1.5 in binary is 1.1.
let mul1 = Float::with_val(4, 1.5);
// -13 in binary is -1101.
let mul2 = Float::with_val(4, -13);
// 24 + 1.5 * -13 = 4.5
let add = Float::with_val(4, &a + &mul1 * &mul2);
assert_eq!(add, 4.5);
// 24 - 1.5 * -13 = 43.5, rounded to 44 using four bits of precision.
let sub = a - &mul1 * &mul2;
assert_eq!(sub, 44);

// With separate addition and multiplication:
let a = Float::with_val(4, 24);
// No borrows, so multiplication is computed immediately.
// 1.5 * -13 = -19.5 (binary -10011.1), rounded to -20.
let separate_add = a + mul1 * mul2;
assert_eq!(separate_add, 4);

The incomplete-computation value obtained from multiplying two Float references can also be added to or subtracted from another such incomplete-computation value, so that two muliplications and an addition are fused with only one rounding operation taking place.

use rug::Float;
let a = Float::with_val(53, 24);
let b = Float::with_val(53, 1.5);
let c = Float::with_val(53, 12);
let d = Float::with_val(53, 2);
// 24 * 1.5 + 12 * 2 = 60
let add = Float::with_val(53, &a * &b + &c * &d);
assert_eq!(add, 60);
// 24 * 1.5 - 12 * 2 = 12
let sub = Float::with_val(53, &a * &b - &c * &d);
assert_eq!(sub, 12);

The Float type supports various functions. Most methods have four versions:

The first method consumes the operand and rounds the returned Float to the nearest representable value.
The second method has a _mut suffix, mutates the operand and rounds it the nearest representable value.
The third method has a _round suffix, mutates the operand, applies the specified rounding method, and returns the rounding direction:
- Ordering::Less if the stored value is less than the exact result,
- Ordering::Equal if the stored value is equal to the exact result,
- Ordering::Greater if the stored value is greater than the exact result.
The fourth method has a _ref suffix and borrows the operand. The returned item is an incomplete-computation value that can be assigned to a Float; the rounding method is selected during the assignment.

use rug::Float;
use rug::float::Round;
use std::cmp::Ordering;
let expected = 0.9490_f64;

// 1. consume the operand, round to nearest
let a = Float::with_val(53, 1.25);
let sin_a = a.sin();
assert!((sin_a - expected).abs() < 0.0001);

// 2. mutate the operand, round to nearest
let mut b = Float::with_val(53, 1.25);
b.sin_mut();
assert!((b - expected).abs() < 0.0001);

// 3. mutate the operand, apply specified rounding
let mut c = Float::with_val(4, 1.25);
// using 4 significant bits, 0.9490 is rounded down to 0.9375
let dir = c.sin_round(Round::Nearest);
assert_eq!(c, 0.9375);
assert_eq!(dir, Ordering::Less);

// 4. borrow the operand
let d = Float::with_val(53, 1.25);
let r = d.sin_ref();
let sin_d = Float::with_val(53, r);
assert!((sin_d - expected).abs() < 0.0001);
// d was not consumed
assert_eq!(d, 1.25);

The following example is a translation of the MPFR sample found on the MPFR website. The program computes a lower bound on 1 + 1/1! + 1/2! + … + 1/100! using 200-bit precision. The program writes:

Sum is 2.7182818284590452353602874713526624977572470936999595749669131

extern crate rug;
use rug::Float;
use rug::float::{Round};
use rug::ops::{AddAssignRound, AssignRound, MulAssignRound};

fn main() {
    let mut t = Float::with_val(200, 1.0);
    let mut s = Float::with_val(200, 1.0);
    let mut u = Float::new(200);
    for i in 1..101_u32 {
        // multiply t by i in place, round towards plus infinity
        t.mul_assign_round(i, Round::Up);
        // set u to 1/t, round towards minus infinity
        u.assign_round(t.recip_ref(), Round::Down);
        // increase s by u in place, round towards minus infinity
        s.add_assign_round(&u, Round::Down);
    }
    // `None` means the number of printed digits depends on the precision
    let sr = s.to_string_radix_round(10, None, Round::Down);
    println!("Sum is {}", sr);
}

Methods

`impl Float`
[src]

`fn new(prec: u32) -> Self`
[src]

Create a new Float with the specified precision and with value 0.

Examples

use rug::Float;
let f = Float::new(53);
assert_eq!(f.prec(), 53);
assert_eq!(f, 0);

Panics

Panics if prec is out of the allowed range.

`fn with_val<T>(prec: u32, val: T) -> Self where Float: Assign<T>,`
[src]

Create a new Float with the specified precision and with the given value, rounding to the nearest.

Examples

use rug::Float;
let f = Float::with_val(53, 1.3);
assert_eq!(f.prec(), 53);
assert_eq!(f, 1.3);

Panics

Panics if prec is out of the allowed range.

`fn with_val_round<T>(prec: u32, val: T, round: Round) -> (Self, Ordering) where Self: AssignRound<T, Round = Round, Ordering = Ordering>,`
[src]

Create a new Float with the specified precision and with the given value, applying the specified rounding method.

Examples

use rug::Float;
use rug::float::Round;
use std::cmp::Ordering;
let (f1, dir) = Float::with_val_round(4, 3.3, Round::Nearest);
// 3.3 with precision 4 is rounded down to 3.25
assert_eq!(f1.prec(), 4);
assert_eq!(f1, 3.25);
assert_eq!(dir, Ordering::Less);
let (f2, dir) = Float::with_val_round(4, 3.3, Round::Up);
// 3.3 rounded up to 3.5
assert_eq!(f2.prec(), 4);
assert_eq!(f2, 3.5);
assert_eq!(dir, Ordering::Greater);

Panics

Panics if prec is out of the allowed range.

`fn prec(&self) -> u32`
[src]

Returns the precision.

Examples

use rug::Float;
let f = Float::new(53);
assert_eq!(f.prec(), 53);

`fn set_prec(&mut self, prec: u32)`
[src]

Sets the precision, rounding to the nearest.

Examples

use rug::Float;
// 16.25 has seven significant bits (binary 10000.01)
let mut f = Float::with_val(53, 16.25);
f.set_prec(5);
assert_eq!(f, 16);
assert_eq!(f.prec(), 5);

Panics

Panics if prec is out of the allowed range.

`fn set_prec_round(&mut self, prec: u32, round: Round) -> Ordering`
[src]

Sets the precision, applying the specified rounding method.

Examples

use rug::Float;
use rug::float::Round;
use std::cmp::Ordering;
// 16.25 has seven significant bits (binary 10000.01)
let mut f = Float::with_val(53, 16.25);
let dir = f.set_prec_round(5, Round::Up);
assert_eq!(f, 17);
assert_eq!(dir, Ordering::Greater);
assert_eq!(f.prec(), 5);

Panics

Panics if prec is out of the allowed range.

`fn parse<S: AsRef<[u8]>>(src: S) -> Result<ParseIncomplete, ParseFloatError>`
[src]

Parses a decimal string or byte slice into a Float.

AssignRound<Src> for Float is implemented with the unwrapped returned object as Src.

The string can start with an optional minus or plus sign and must then have one or more significant digits with an optional decimal point. This can optionally be followed by an exponent; the exponent can start with a separator 'e', 'E' or '@', and is followed by an optional minus or plus sign and by one or more decimal digits.

Alternatively, the string can indicate the special values infinity or NaN. Infinity can be represented as "inf, "infinity", "@inf@" or "@infinity@",and NaN can be represented as "nan" or "@nan@". All of these special representations are case insensitive. The NaN representation may also include a possibly-empty string of ASCII letters, digits and underscores enclosed in brackets, e.g. "nan(char_sequence_1)".

ASCII whitespace is ignored everywhere in the string except in the substrings specified above for special values; for example " @inf@ " is accepted but "@ inf @" is not. Underscores are ignored anywhere in digit strings except before the first digit and between the exponent separator and the first digit of the exponent.

Examples

use rug::Float;

let valid = Float::parse("12.25e-4");
let f = Float::with_val(53, valid.unwrap());
assert_eq!(f, 12.25e-4);

let invalid = Float::parse(".e-4");
assert!(invalid.is_err());

`fn parse_radix<S: AsRef<[u8]>>( src: S, radix: i32 ) -> Result<ParseIncomplete, ParseFloatError>`
[src]

Parses a string or byte slice into a Float.

AssignRound<Src> for Float is implemented with the unwrapped returned object as Src.

The string can start with an optional minus or plus sign and must then have one or more significant digits with an optional point. This can optionally be followed by an exponent; the exponent can start with a separator 'e' or 'E' if the radix ≤ 10, or '@' for any radix, and is followed by an optional minus or plus sign and by one or more decimal digits.

Alternatively, the string can indicate the special values infinity or NaN. If the radix ≤ 10, infinity can be represented as "inf" or "infinity", and NaN can be represented as "nan". For any radix, infinity can also be represented as "@inf@" or "@infinity@", and NaN can be represented as "@nan@". All of these special representations are case insensitive. The NaN representation may also include a possibly-empty string of ASCII letters, digits and underscores enclosed in brackets, e.g. "nan(char_sequence_1)".

ASCII whitespace is ignored everywhere in the string except in the substrings specified above for special values; for example " @inf@ " is accepted but "@ inf @" is not. Underscores are ignored anywhere in digit strings except before the first digit and between the exponent separator and the first digit of the exponent.

Examples

use rug::Float;

let valid1 = Float::parse_radix("12.23e-4", 4);
let f1 = Float::with_val(53, valid1.unwrap());
assert_eq!(f1, (2.0 + 4.0 * 1.0 + 0.25 * (2.0 + 0.25 * 3.0)) / 256.0);
let valid2 = Float::parse_radix("12.yz@2", 36);
let f2 = Float::with_val(53, valid2.unwrap());
assert_eq!(f2, 35 + 36 * (34 + 36 * (2 + 36 * 1)));

let invalid = Float::parse_radix("ffe-2", 16);
assert!(invalid.is_err());

Panics

Panics if radix is less than 2 or greater than 36.

`fn to_integer(&self) -> Option<Integer>`
[src]

Converts to an Integer, rounding to the nearest.

Examples

use rug::Float;
let f = Float::with_val(53, 13.7);
let i = match f.to_integer() {
    Some(i) => i,
    None => unreachable!(),
};
assert_eq!(i, 14);

`fn to_integer_round(&self, round: Round) -> Option<(Integer, Ordering)>`
[src]

Converts to an Integer, applying the specified rounding method.

Examples

use rug::Float;
use rug::float::Round;
use std::cmp::Ordering;
let f = Float::with_val(53, 13.7);
let (i, dir) = match f.to_integer_round(Round::Down) {
    Some(i_dir) => i_dir,
    None => unreachable!(),
};
assert_eq!(i, 13);
assert_eq!(dir, Ordering::Less);

`fn to_integer_exp(&self) -> Option<(Integer, i32)>`
[src]

If the value is a finite number, returns an Integer and exponent such that self is exactly equal to the integer multiplied by two raised to the power of the exponent.

Examples

use rug::{Assign, Float};
use rug::float::Special;
let mut float = Float::with_val(16, 6.5);
// 6.5 in binary is 110.1
// Since the precision is 16 bits, this becomes
// 1101_0000_0000_0000 times two to the power of -12
let (int, exp) = float.to_integer_exp().unwrap();
assert_eq!(int, 0b1101_0000_0000_0000);
assert_eq!(exp, -13);

float.assign(0);
let (zero, _) = float.to_integer_exp().unwrap();
assert_eq!(zero, 0);

float.assign(Special::Infinity);
assert!(float.to_integer_exp().is_none());

`fn to_rational(&self) -> Option<Rational>`
[src]

If the value is a finite number, returns a Rational number preserving all the precision of the value.

Examples

use rug::{Float, Rational};
use rug::float::Round;
use std::str::FromStr;
use std::cmp::Ordering;

// Consider the number 123,456,789 / 10,000,000,000.
let parse = Float::parse("0.0123456789").unwrap();
let (f, f_rounding) = Float::with_val_round(35, parse, Round::Down);
assert_eq!(f_rounding, Ordering::Less);
let r = Rational::from_str("123456789/10000000000").unwrap();
// Set fr to the value of f exactly.
let fr = f.to_rational().unwrap();
// Since f == fr and f was rounded down, r != fr.
assert_ne!(r, fr);
let (frf, frf_rounding) = Float::with_val_round(35, &fr, Round::Down);
assert_eq!(frf_rounding, Ordering::Equal);
assert_eq!(frf, f);
assert_eq!(format!("{:.9}", frf), "1.23456789e-2");

In the following example, the Float values can be represented exactly.

use rug::Float;

let large_f = Float::with_val(16, 6.5);
let large_r = large_f.to_rational().unwrap();
let small_f = Float::with_val(16, -0.125);
let small_r = small_f.to_rational().unwrap();

assert_eq!(*large_r.numer(), 13);
assert_eq!(*large_r.denom(), 2);
assert_eq!(*small_r.numer(), -1);
assert_eq!(*small_r.denom(), 8);

`fn to_i32_saturating(&self) -> Option<i32>`
[src]

Converts to an i32, rounding to the nearest.

If the value is too small or too large for the target type, the minimum or maximum value allowed is returned. If the value is a NaN, None is returned.

Examples

use rug::{Assign, Float};
use std::{i32, u32};
let mut f = Float::with_val(53, -13.7);
assert_eq!(f.to_i32_saturating(), Some(-14));
f.assign(-1e40);
assert_eq!(f.to_i32_saturating(), Some(i32::MIN));
f.assign(u32::MAX);
assert_eq!(f.to_i32_saturating(), Some(i32::MAX));

`fn to_i32_saturating_round(&self, round: Round) -> Option<i32>`
[src]

Converts to an i32, applying the specified rounding method.

If the value is too small or too large for the target type, the minimum or maximum value allowed is returned. If the value is a NaN, None is returned.

Examples

use rug::Float;
use rug::float::Round;
let f = Float::with_val(53, -13.7);
assert_eq!(f.to_i32_saturating_round(Round::Up), Some(-13));

`fn to_u32_saturating(&self) -> Option<u32>`
[src]

Converts to a u32, rounding to the nearest.

If the value is too small or too large for the target type, the minimum or maximum value allowed is returned. If the value is a NaN, None is returned.

Examples

use rug::{Assign, Float};
use std::u32;
let mut f = Float::with_val(53, 13.7);
assert_eq!(f.to_u32_saturating(), Some(14));
f.assign(-1);
assert_eq!(f.to_u32_saturating(), Some(0));
f.assign(1e40);
assert_eq!(f.to_u32_saturating(), Some(u32::MAX));

`fn to_u32_saturating_round(&self, round: Round) -> Option<u32>`
[src]

Converts to a u32, applying the specified rounding method.

If the value is too small or too large for the target type, the minimum or maximum value allowed is returned. If the value is a NaN, None is returned.

Examples

use rug::Float;
use rug::float::Round;
let f = Float::with_val(53, 13.7);
assert_eq!(f.to_u32_saturating_round(Round::Down), Some(13));