Struct Exact

Source

pub struct Exact { /* private fields */ }

Expand description

A Rat wrapper whose add/sub/mul/div succeed only when the result needs no rounding.

use the_q::{Exact, Rat};
let _ = Exact { value: Rat::one() };

use the_q::{Exact, Rat};
let mut e = Exact::new(Rat::one());
e.value = Rat::zero();

Implementations§

Source §

impl Exact

Source

pub fn new(value: Rat) -> Exact

Wraps an already-computed Rat. Always exact: it denotes itself.

use the_q::{Exact, Rat};

let half = Exact::new(Rat::new(1, 2).unwrap());
assert_eq!(half.value(), Rat::new(1, 2).unwrap());

Source

pub fn value(&self) -> Rat

The wrapped value.

use the_q::{Exact, Rat};

let e = Exact::new(Rat::new(3, 4).unwrap());
assert_eq!(e.value(), Rat::new(3, 4).unwrap());

Source

pub fn is_nonneg(&self) -> bool

Whether the wrapped value is nonnegative.

use the_q::{Exact, Rat};

assert!(Exact::new(Rat::new(1, 2).unwrap()).is_nonneg());
assert!(Exact::new(Rat::zero()).is_nonneg());
assert!(!Exact::new(Rat::new(-1, 2).unwrap()).is_nonneg());

Source

pub fn le(a: Exact, b: Exact) -> bool

a <= b.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(1, 3).unwrap());
let b = Exact::new(Rat::new(1, 2).unwrap());
assert!(Exact::le(a, b));
assert!(!Exact::le(b, a));
assert!(Exact::le(a, a));

Source

pub fn checked_add(a: Exact, b: Exact) -> Option<Exact>

a + b, or None if the exact sum needs rounding.

use the_q::{Exact, Rat};

let half = Exact::new(Rat::new(1, 2).unwrap());
let sum = Exact::checked_add(half, half).expect("1/2 + 1/2 is exact");
assert_eq!(sum.value(), Rat::new(1, 1).unwrap());

// The reduced denominator of this sum is about 9.2e18, past the
// budget -- `None`, not a silently rounded answer.
let a = Exact::new(Rat::new(1, 3_037_000_493).unwrap());
let b = Exact::new(Rat::new(1, 3_037_000_499).unwrap());
assert_eq!(Exact::checked_add(a, b), None);

Source

pub fn checked_sub(a: Exact, b: Exact) -> Option<Exact>

a - b, or None if the exact difference needs rounding.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(3, 4).unwrap());
let b = Exact::new(Rat::new(1, 4).unwrap());
let diff = Exact::checked_sub(a, b).expect("3/4 - 1/4 is exact");
assert_eq!(diff.value(), Rat::new(1, 2).unwrap());

Source

pub fn checked_mul(a: Exact, b: Exact) -> Option<Exact>

a * b, or None if the exact product needs rounding.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(2, 3).unwrap());
let b = Exact::new(Rat::new(3, 4).unwrap());
let product = Exact::checked_mul(a, b).expect("(2/3) * (3/4) is exact");
assert_eq!(product.value(), Rat::new(1, 2).unwrap());

Source

pub fn checked_div(a: Exact, b: Exact) -> Option<Exact>

a / b, or None if b is zero or the exact quotient needs rounding.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(1, 2).unwrap());
let b = Exact::new(Rat::new(1, 3).unwrap());
let quotient = Exact::checked_div(a, b).expect("(1/2) / (1/3) is exact");
assert_eq!(quotient.value(), Rat::new(3, 2).unwrap());

// Division by zero is `None`, the same as any other operand that
// leaves the exact path -- `checked_div` does not distinguish the two
// causes (the `Result`-returning `div` does; see below).
assert_eq!(Exact::checked_div(a, Exact::new(Rat::zero())), None);

Source §

impl Exact

Source

pub fn add(a: Exact, b: Exact) -> Result<Exact, ExactError>

a + b, or ExactError::Inexact if the exact sum needs rounding.

use the_q::{Exact, ExactError, Rat};

let half = Exact::new(Rat::new(1, 2).unwrap());
assert_eq!(Exact::add(half, half).unwrap().value(), Rat::new(1, 1).unwrap());

let a = Exact::new(Rat::new(1, 3_037_000_493).unwrap());
let b = Exact::new(Rat::new(1, 3_037_000_499).unwrap());
assert_eq!(Exact::add(a, b), Err(ExactError::Inexact));

Source

pub fn sub(a: Exact, b: Exact) -> Result<Exact, ExactError>

a - b, or ExactError::Inexact if the exact difference needs rounding.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(3, 4).unwrap());
let b = Exact::new(Rat::new(1, 4).unwrap());
assert_eq!(Exact::sub(a, b).unwrap().value(), Rat::new(1, 2).unwrap());

Source

pub fn mul(a: Exact, b: Exact) -> Result<Exact, ExactError>

a * b, or ExactError::Inexact if the exact product needs rounding.

use the_q::{Exact, Rat};

let a = Exact::new(Rat::new(2, 3).unwrap());
let b = Exact::new(Rat::new(3, 4).unwrap());
assert_eq!(Exact::mul(a, b).unwrap().value(), Rat::new(1, 2).unwrap());

Source

pub fn div(a: Exact, b: Exact) -> Result<Exact, ExactError>

a / b, or ExactError::DivisionByZero / ExactError::Inexact.

use the_q::{Exact, ExactError, Rat};

let a = Exact::new(Rat::new(1, 2).unwrap());
let b = Exact::new(Rat::new(1, 3).unwrap());
assert_eq!(Exact::div(a, b).unwrap().value(), Rat::new(3, 2).unwrap());

assert_eq!(
    Exact::div(a, Exact::new(Rat::zero())),
    Err(ExactError::DivisionByZero),
);