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.

There are two versions of most methods:

The first rounds the returned or stored Float to the nearest representable value.
The second applies the specified rounding method, and returns the rounding direction:
- Ordering::Less if the returned/stored Float is less than the exact result,
- Ordering::Equal if the returned/stored Float is equal to the exact result,
- Ordering::Greater if the returned/stored Float is greater than the exact result,

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);

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::{AssignRound, Float};
use rug::float::Round;
use rug::ops::{AddAssignRound, 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) -> Float`

Create a new floating-point number 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) -> Float where Float: Assign<T>,`

Create a new floating-point number 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) -> (Float, Ordering) where Float: AssignRound<T, Round = Round, Ordering = Ordering>,`

Create a new floating-point number 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`

Returns the precision.

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

Sets the precision, rounding to the nearest.

Panics

Panics if prec is out of the allowed range.

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

Sets the precision, applying the specified rounding method.

Panics

Panics if prec is out of the allowed range.

`fn from_str(src: &str, prec: u32) -> Result<Float, ParseFloatError>`

Parses a Float with the specified precision, rounding to the nearest.

See the corresponding assignment.

`fn from_str_round( src: &str, prec: u32, round: Round ) -> Result<(Float, Ordering), ParseFloatError>`

Parses a Float with the specified precision, applying the specified rounding.

See the corresponding assignment.

`fn from_str_radix( src: &str, radix: i32, prec: u32 ) -> Result<Float, ParseFloatError>`

Parses a Float with the specified radix and precision, rounding to the nearest.

See the corresponding assignment.

Panics

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

`fn from_str_radix_round( src: &str, radix: i32, prec: u32, round: Round ) -> Result<(Float, Ordering), ParseFloatError>`

Parses a Float with the specified radix and precision, applying the specified rounding.

See the corresponding assignment.

Panics

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

`fn valid_str_radix(src: &str, radix: i32) -> Result<ValidFloat, ParseFloatError>`

Checks if a Float can be parsed.

If this method does not return an error, neither will any other function that parses a Float. If this method returns an error, the other functions will return the same error.

The string can start with an optional minus or plus sign. Whitespace is not allowed anywhere in the string, including in the beginning and end.

Examples

use rug::Float;

let valid1 = Float::valid_str_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::valid_str_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::valid_str_radix("ffe-2", 16);
let invalid_f = Float::from_str_radix("ffe-2", 16, 53);
assert_eq!(invalid.unwrap_err(), invalid_f.unwrap_err());

Panics

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

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

Converts to an integer, rounding to the nearest.

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

Converts to an integer, applying the specified rounding method.

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

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

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 res = Float::from_str_round("0.0123456789", 35, Round::Down);
let (f, f_rounding) = res.unwrap();
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>`

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.

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

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.

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

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.

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

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.