Struct rug::rational::SmallRational

#[repr(C)]
pub struct SmallRational { /* fields omitted */ }

A small rational number that does not require any memory allocation.

This can be useful when you have a numerator and denominator that are 32-bit or 64-bit integers and you need a reference to a Rational.

Although no allocation is required, setting the value of a SmallRational does require some computation, as the numerator and denominator need to be canonicalized.

The SmallRational type can be coerced to a Rational, as it implements Deref with a Rational target.

Examples

use rug::Rational;
use rug::rational::SmallRational;
// `a` requires a heap allocation
let mut a = Rational::from((100, 13));
// `b` can reside on the stack
let b = SmallRational::from((-100, 21));
a /= &*b;
assert_eq!(*a.numer(), -21);
assert_eq!(*a.denom(), 13);

Methods

impl SmallRational

fn new() -> SmallRational

Creates a SmallRational with value 0.

unsafe fn from_canonicalized_32(neg: bool, num: u32, den: u32) -> SmallRational

Creates a SmallRational from a 32-bit numerator and denominator, assuming they are in canonical form.

Safety

This function is unsafe because

• it does not check that the denominator is not zero, and

• it does not canonicalize the numerator and denominator.

The rest of the library assumes that SmallRational and Rational structures keep their numerators and denominators canonicalized.

Examples

use rug::rational::SmallRational;
let from_unsafe = unsafe {
    SmallRational::from_canonicalized_32(true, 13, 10)
};
// from_safe is canonicalized to the same form as from_unsafe
let from_safe = SmallRational::from((130, -100));
assert_eq!(from_unsafe.numer(), from_safe.numer());
assert_eq!(from_unsafe.denom(), from_safe.denom());

unsafe fn from_canonicalized_64(neg: bool, num: u64, den: u64) -> SmallRational

Creates a SmallRational from a 64-bit numerator and denominator, assuming they are in canonical form.

Safety

This function is unsafe because

• it does not check that the denominator is not zero, and

• it does not canonicalize the numerator and denominator.

The rest of the library assumes that SmallRational and Rational structures keep their numerators and denominators canonicalized.

Examples

use rug::rational::SmallRational;
let from_unsafe = unsafe {
    SmallRational::from_canonicalized_64(true, 13, 10)
};
// from_safe is canonicalized to the same form as from_unsafe

let from_safe = SmallRational::from((130, -100));
assert_eq!(from_unsafe.numer(), from_safe.numer());
assert_eq!(from_unsafe.denom(), from_safe.denom());

unsafe fn assign_canonicalized_32(&mut self, neg: bool, num: u32, den: u32)

Sets a SmallRational to a 32-bit numerator and denominator, assuming they are in canonical form.

Safety

This function is unsafe because

• it does not check that the denominator is not zero, and

• it does not canonicalize the numerator and denominator.

The rest of the library assumes that SmallRational and Rational structures keep their numerators and denominators canonicalized.

Examples

use rug::rational::SmallRational;
let mut from_unsafe = SmallRational::new();
unsafe {
    from_unsafe.assign_canonicalized_32(true, 13, 10)
};
// from_safe is canonicalized to the same form as from_unsafe
let from_safe = SmallRational::from((130, -100));
assert_eq!(from_unsafe.numer(), from_safe.numer());
assert_eq!(from_unsafe.denom(), from_safe.denom());

unsafe fn assign_canonicalized_64(&mut self, neg: bool, num: u64, den: u64)

Sets a SmallRational to a 64-bit numerator and denominator, assuming they are in canonical form.

Safety

This function is unsafe because

• it does not check that the denominator is not zero, and

• it does not canonicalize the numerator and denominator.

The rest of the library assumes that SmallRational and Rational structures keep their numerators and denominators canonicalized.

Examples

use rug::rational::SmallRational;
let mut from_unsafe = SmallRational::new();
unsafe {
    from_unsafe.assign_canonicalized_64(true, 13, 10)
};
// from_safe is canonicalized to the same form as from_unsafe
let from_safe = SmallRational::from((130, -100));
assert_eq!(from_unsafe.numer(), from_safe.numer());
assert_eq!(from_unsafe.denom(), from_safe.denom());

Methods from Deref<Target = Rational>

fn to_integer(&self) -> Integer

Converts to an Integer, rounding towards zero.

Examples

use rug::Rational;
let pos = Rational::from((139, 10));
let posi = pos.to_integer();
assert_eq!(posi, 13);
let neg = Rational::from((-139, 10));
let negi = neg.to_integer();
assert_eq!(negi, -13);

fn copy_to_integer(&self, i: &mut Integer)

Converts to an Integer inside i, rounding towards zero.

Examples

use rug::{Integer, Rational};
let mut i = Integer::new();
assert_eq!(i, 0);
let pos = Rational::from((139, 10));
pos.copy_to_integer(&mut i);
assert_eq!(i, 13);
let neg = Rational::from((-139, 10));
neg.copy_to_integer(&mut i);
assert_eq!(i, -13);

fn to_f32(&self) -> f32

Converts to an f32, rounding towards zero.

Examples

use rug::Rational;
use rug::rational::SmallRational;
use std::f32;
let min = Rational::from_f32(f32::MIN).unwrap();
let minus_small = min - &*SmallRational::from((7, 2));
// minus_small is truncated to f32::MIN
assert_eq!(minus_small.to_f32(), f32::MIN);
let times_three_two = minus_small * &*SmallRational::from((3, 2));
// times_three_two is too small
assert_eq!(times_three_two.to_f32(), f32::NEG_INFINITY);

fn to_f64(&self) -> f64

Converts to an f64, rounding towards zero.

Examples

use rug::Rational;
use rug::rational::SmallRational;
use std::f64;

// An `f64` has 53 bits of precision.
let exact = 0x1f_1234_5678_9aff_u64;
let den = 0x1000_u64;
let r = Rational::from((exact, den));
assert_eq!(r.to_f64(), exact as f64 / den as f64);

// large has 56 ones
let large = 0xff_1234_5678_9aff_u64;
// trunc has 53 ones followed by 3 zeros
let trunc = 0xff_1234_5678_9af8_u64;
let j = Rational::from((large, den));
assert_eq!(j.to_f64(), trunc as f64 / den as f64);

let max = Rational::from_f64(f64::MAX).unwrap();
let plus_small = max + &*SmallRational::from((7, 2));
// plus_small is truncated to f64::MAX
assert_eq!(plus_small.to_f64(), f64::MAX);
let times_three_two = plus_small * &*SmallRational::from((3, 2));
// times_three_two is too large
assert_eq!(times_three_two.to_f64(), f64::INFINITY);

fn to_string_radix(&self, radix: i32) -> String

Returns a string representation for the specified radix.

Examples

use rug::Rational;
let r1 = Rational::from(0);
assert_eq!(r1.to_string_radix(10), "0");
let r2 = Rational::from((15, 5));
assert_eq!(r2.to_string_radix(10), "3");
let r3 = Rational::from((10, -6));
assert_eq!(r3.to_string_radix(10), "-5/3");
assert_eq!(r3.to_string_radix(5), "-10/3");

Panics

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

fn numer(&self) -> &Integer

Borrows the numerator as an Integer.

Examples

use rug::Rational;
let r = Rational::from((12, -20));
// r will be canonicalized to -3 / 5
assert_eq!(*r.numer(), -3)

fn denom(&self) -> &Integer

Borrows the denominator as an Integer.

Examples

use rug::Rational;
let r = Rational::from((12, -20));
// r will be canonicalized to -3 / 5
assert_eq!(*r.denom(), 5);

fn as_numer_denom(&self) -> (&Integer, &Integer)

Borrows the numerator and denominator as Integer values.

Examples

use rug::Rational;
let r = Rational::from((12, -20));
// r will be canonicalized to -3 / 5
let (num, den) = r.as_numer_denom();
assert_eq!(*num, -3);
assert_eq!(*den, 5);

fn into_numer_denom(self) -> (Integer, Integer)

Converts into numerator and denominator integers.

This function reuses the allocated memory and does not allocate any new memory.

Examples

use rug::Rational;
let r = Rational::from((12, -20));
// r will be canonicalized to -3 / 5
let (num, den) = r.into_numer_denom();
assert_eq!(num, -3);
assert_eq!(den, 5);

fn sign(&self) -> Ordering

Returns Ordering::Less if the number is less than zero, Ordering::Greater if it is greater than zero, or Ordering::Equal if it is equal to zero.

fn abs(self) -> Rational

Computes the absolute value.

Examples

use rug::Rational;
let r = Rational::from((-100, 17));
let abs = r.abs();
assert_eq!(abs, (100, 17));

fn abs_ref(&self) -> AbsRef

Computes the absolute value.

Examples

use rug::Rational;
let r = Rational::from((-100, 17));
let rr = r.abs_ref();
let abs = Rational::from(rr);
assert_eq!(abs, (100, 17));

fn recip(self) -> Rational

Computes the reciprocal.

Examples

use rug::Rational;
let r = Rational::from((-100, 17));
let recip = r.recip();
assert_eq!(recip, (-17, 100));

Panics

Panics if the value is zero.

fn recip_ref(&self) -> RecipRef

Computes the reciprocal.

Examples

use rug::Rational;
let r = Rational::from((-100, 17));
let rr = r.recip_ref();
let recip = Rational::from(rr);
assert_eq!(recip, (-17, 100));

fn ceil(self) -> Integer

Rounds the number upwards (towards plus infinity) and returns it as an Integer.

Examples

use rug::Rational;
// -3.7
let r1 = Rational::from((-37, 10));
let i1 = r1.ceil();
assert_eq!(i1, -3);
// 3.3
let r2 = Rational::from((33, 10));
let i2 = r2.ceil();
assert_eq!(i2, 4);

fn ceil_ref(&self) -> CeilRef

Rounds the number upwards (towards plus infinity).

Examples

use rug::{Assign, Integer, Rational};
let mut ceil = Integer::new();
// -3.7
let r1 = Rational::from((-37, 10));
ceil.assign(r1.ceil_ref());
assert_eq!(ceil, -3);
// 3.3
let r2 = Rational::from((33, 10));
ceil.assign(r2.ceil_ref());
assert_eq!(ceil, 4);

fn floor(self) -> Integer

Rounds the number downwards (towards minus infinity).

Examples

use rug::Rational;
// -3.7
let r1 = Rational::from((-37, 10));
let i1 = r1.floor();
assert_eq!(i1, -4);
// 3.3
let r2 = Rational::from((33, 10));
let i2 = r2.floor();
assert_eq!(i2, 3);

fn floor_ref(&self) -> FloorRef

Rounds the number downwards (towards minus infinity).

Examples

use rug::{Assign, Integer, Rational};
let mut floor = Integer::new();
// -3.7
let r1 = Rational::from((-37, 10));
floor.assign(r1.floor_ref());
assert_eq!(floor, -4);
// 3.3
let r2 = Rational::from((33, 10));
floor.assign(r2.floor_ref());
assert_eq!(floor, 3);

fn round(self) -> Integer

Rounds the number to the nearest integer and returns it as an Integer.

When the number lies exactly between two integers, it is rounded away from zero.

Examples

use rug::Rational;
// -3.5
let r1 = Rational::from((-35, 10));
let i1 = r1.round();
assert_eq!(i1, -4);
// 3.7
let r2 = Rational::from((37, 10));
let i2 = r2.round();
assert_eq!(i2, 4);

fn round_ref(&self) -> RoundRef

Rounds the number to the nearest integer.

When the number lies exactly between two integers, it is rounded away from zero.

Examples

use rug::{Assign, Integer, Rational};
let mut round = Integer::new();
// -3.5
let r1 = Rational::from((-35, 10));
round.assign(r1.round_ref());
assert_eq!(round, -4);
// 3.7
let r2 = Rational::from((37, 10));
round.assign(r2.round_ref());
assert_eq!(round, 4);

fn trunc(self) -> Integer

Rounds the number towards zero and returns it as an Integer.

Examples

use rug::Rational;
// -3.7
let r1 = Rational::from((-37, 10));
let i1 = r1.trunc();
assert_eq!(i1, -3);
// 3.3
let r2 = Rational::from((33, 10));
let i2 = r2.trunc();
assert_eq!(i2, 3);

fn trunc_ref(&self) -> TruncRef

Rounds the number towards zero.

Examples

use rug::{Assign, Integer, Rational};
let mut trunc = Integer::new();
// -3.7
let r1 = Rational::from((-37, 10));
trunc.assign(r1.trunc_ref());
assert_eq!(trunc, -3);
// 3.3
let r2 = Rational::from((33, 10));
trunc.assign(r2.trunc_ref());
assert_eq!(trunc, 3);

fn fract(self) -> Rational

Computes the fractional part of the number.

Examples

use rug::Rational;
// -100/17 = -5 15/17
let r = Rational::from((-100, 17));
let fract = r.fract();
assert_eq!(fract, (-15, 17));

fn fract_ref(&self) -> FractRef

Computes the fractional part of the number.

Examples

use rug::Rational;
let r = Rational::from((-100, 17));
let rr = r.fract_ref();
let fract = Rational::from(rr);
assert_eq!(fract, (-15, 17));

fn fract_trunc(self, trunc: Integer) -> (Rational, Integer)

Computes the fractional and truncated parts of the number.

The initial value of trunc is ignored.

Examples

use rug::{Integer, Rational};
// -100/17 = -5 15/17
let r = Rational::from((-100, 17));
let (fract, trunc) = r.fract_trunc(Integer::new());
assert_eq!(fract, (-15, 17));
assert_eq!(trunc, -5);

fn fract_trunc_ref(&self) -> FractTruncRef

Computes the fractional and truncated parts of the number.

Examples

use rug::{Assign, Integer, Rational};
// -100/17 = -5 15/17
let r = Rational::from((-100, 17));
let r_ref = r.fract_trunc_ref();
let (mut fract, mut trunc) = (Rational::new(), Integer::new());
(&mut fract, &mut trunc).assign(r_ref);
assert_eq!(fract, (-15, 17));
assert_eq!(trunc, -5);

Trait Implementations

impl Default for SmallRational

fn default() -> SmallRational

Returns the "default value" for a type.

impl Deref for SmallRational

type Target = Rational

The resulting type after dereferencing

fn deref(&self) -> &Rational

The method called to dereference a value

impl<T> From<T> for SmallRational where
    SmallRational: Assign<T>, 

fn from(val: T) -> SmallRational

Performs the conversion.

impl Assign<i32> for SmallRational

fn assign(&mut self, num: i32)

Peforms the assignement.

impl Assign<i64> for SmallRational

fn assign(&mut self, num: i64)

Peforms the assignement.

impl Assign<u32> for SmallRational

fn assign(&mut self, num: u32)

Peforms the assignement.

impl Assign<u64> for SmallRational

fn assign(&mut self, num: u64)

Peforms the assignement.

impl Assign<(i32, i32)> for SmallRational

fn assign(&mut self, (num, den): (i32, i32))

Peforms the assignement.

impl Assign<(i64, i64)> for SmallRational

fn assign(&mut self, (num, den): (i64, i64))

Peforms the assignement.

impl Assign<(i32, u32)> for SmallRational

fn assign(&mut self, (num, den): (i32, u32))

Peforms the assignement.

impl Assign<(i64, u64)> for SmallRational

fn assign(&mut self, (num, den): (i64, u64))

Peforms the assignement.

impl Assign<(u32, i32)> for SmallRational

fn assign(&mut self, (num, den): (u32, i32))

Peforms the assignement.

impl Assign<(u64, i64)> for SmallRational

fn assign(&mut self, (num, den): (u64, i64))

Peforms the assignement.

impl Assign<(u32, u32)> for SmallRational

fn assign(&mut self, (num, den): (u32, u32))

Peforms the assignement.

impl Assign<(u64, u64)> for SmallRational

fn assign(&mut self, (num, den): (u64, u64))

Peforms the assignement.