Struct rug::rational::SmallRational

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 primitive integer-types such as i64 or u8, 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<Target = Rational>.

Examples

use rug::{rational::SmallRational, Rational};
// `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

pub fn new() -> Self

Creates a SmallRational with value 0.

Examples

use rug::rational::SmallRational;
let r = SmallRational::new();
// Use r as if it were Rational.
assert_eq!(*r.numer(), 0);
assert_eq!(*r.denom(), 1);

pub unsafe fn as_nonreallocating_rational(&mut self) -> &mut Rational

Returns a mutable reference to a Rational number for simple operations that do not need to allocate more space for the numerator or denominator.

Safety

It is undefined behaviour to perform operations that reallocate the internal data of the referenced Rational number or to swap it with another number, although it is allowed to swap the numerator and denominator allocations, such as in the reciprocal operation recip_mut.

Some GMP functions swap the allocations of their target operands; calling such functions with the mutable reference returned by this method can lead to undefined behaviour.

Examples

use rug::rational::SmallRational;
let mut r = SmallRational::from((-15i32, 47i32));
let num_capacity = r.numer().capacity();
let den_capacity = r.denom().capacity();
// reciprocating this will not require reallocations
unsafe {
    r.as_nonreallocating_rational().recip_mut();
}
assert_eq!(*r, (-47, 15));
assert_eq!(r.numer().capacity(), num_capacity);
assert_eq!(r.denom().capacity(), den_capacity);

pub unsafe fn from_canonical<Num: ToSmall, Den: ToSmall>(
    num: Num,
    den: Den
) -> Self

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

Safety

This method leads to undefined behaviour if den is zero or if num and den have common factors.

Examples

use rug::rational::SmallRational;
let from_unsafe = unsafe { SmallRational::from_canonical(-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());

pub unsafe fn assign_canonical<Num: ToSmall, Den: ToSmall>(
    &mut self,
    num: Num,
    den: Den
)

Assigns a numerator and denominator to a SmallRational, assuming they are in canonical form.

Safety

This method leads to undefined behaviour if den is zero or negative, or if num and den have common factors.

Examples

use rug::{rational::SmallRational, Assign};
let mut a = SmallRational::new();
unsafe {
    a.assign_canonical(-13, 10);
}
// b is canonicalized to the same form as a
let mut b = SmallRational::new();
b.assign((130, -100));
assert_eq!(a.numer(), b.numer());
assert_eq!(a.denom(), b.denom());

Methods from Deref<Target = Rational>

pub fn as_raw(&self) -> *const mpq_t

Returns a pointer to the inner GMP rational number.

The returned pointer will be valid for as long as self is valid.

Examples

use gmp_mpfr_sys::gmp;
use rug::Rational;
let r = Rational::from((-145, 10));
let q_ptr = r.as_raw();
unsafe {
    let d = gmp::mpq_get_d(q_ptr);
    assert_eq!(d, -14.5);
}
// r is still valid
assert_eq!(r, (-145, 10));

pub fn to_f32(&self) -> f32

Converts to an f32, rounding towards zero.

Examples

use core::f32;
use rug::{rational::SmallRational, Rational};
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);

pub fn to_f64(&self) -> f64

Converts to an f64, rounding towards zero.

Examples

use core::f64;
use rug::{rational::SmallRational, Rational};

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

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

Returns a string representation for the specified radix.

Panics

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

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

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

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

pub fn as_neg(&self) -> BorrowRational

Borrows a negated copy of the Rational number.

The returned object implements Deref<Target = Rational>.

This method performs a shallow copy and negates it, and negation does not change the allocated data.

Examples

use rug::Rational;
let r = Rational::from((7, 11));
let neg_r = r.as_neg();
assert_eq!(*neg_r, (-7, 11));
// methods taking &self can be used on the returned object
let reneg_r = neg_r.as_neg();
assert_eq!(*reneg_r, (7, 11));
assert_eq!(*reneg_r, r);

pub fn as_abs(&self) -> BorrowRational

Borrows an absolute copy of the Rational number.

The returned object implements Deref<Target = Rational>.

This method performs a shallow copy and possibly negates it, and negation does not change the allocated data.

Examples

use rug::Rational;
let r = Rational::from((-7, 11));
let abs_r = r.as_abs();
assert_eq!(*abs_r, (7, 11));
// methods taking &self can be used on the returned object
let reabs_r = abs_r.as_abs();
assert_eq!(*reabs_r, (7, 11));
assert_eq!(*reabs_r, *abs_r);

pub fn as_recip(&self) -> BorrowRational

Borrows a reciprocal copy of the Rational number.

The returned object implements Deref<Target = Rational>.

This method performs some shallow copying, swapping numerator and denominator and making sure the sign is in the numerator.

Panics

Panics if the value is zero.

Examples

use rug::Rational;
let r = Rational::from((-7, 11));
let recip_r = r.as_recip();
assert_eq!(*recip_r, (-11, 7));
// methods taking &self can be used on the returned object
let rerecip_r = recip_r.as_recip();
assert_eq!(*rerecip_r, (-7, 11));
assert_eq!(*rerecip_r, r);

pub fn cmp0(&self) -> Ordering

Returns the same result as self.cmp(&0.into()), but is faster.

Examples

use core::cmp::Ordering;
use rug::Rational;
assert_eq!(Rational::from((-5, 7)).cmp0(), Ordering::Less);
assert_eq!(Rational::from(0).cmp0(), Ordering::Equal);
assert_eq!(Rational::from((5, 7)).cmp0(), Ordering::Greater);

pub fn cmp_abs(&self, other: &Self) -> Ordering

Compares the absolute values.

Examples

use core::cmp::Ordering;
use rug::Rational;
let a = Rational::from((-23, 10));
let b = Rational::from((-47, 5));
assert_eq!(a.cmp(&b), Ordering::Greater);
assert_eq!(a.cmp_abs(&b), Ordering::Less);

pub fn abs_ref(&self) -> AbsIncomplete

Computes the absolute value.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

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

pub fn signum_ref(&self) -> SignumIncomplete

Computes the signum.

• 0 if the value is zero
• 1 if the value is positive
• −1 if the value is negative

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Integer
• Assign<Src> for Rational
• From<Src> for Integer
• From<Src> for Rational

Examples

use rug::{Integer, Rational};
let r = Rational::from((-100, 17));
let r_ref = r.signum_ref();
let signum = Integer::from(r_ref);
assert_eq!(signum, -1);

pub fn clamp_ref<'min, 'max, Min, Max>(
    &self,
    min: &'min Min,
    max: &'max Max
) -> ClampIncomplete<'_, 'min, 'max, Min, Max> where
    Self: PartialOrd<Min> + PartialOrd<Max> + for<'a> Assign<&'a Min> + for<'a> Assign<&'a Max>, 

Clamps the value within the specified bounds.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Panics

Panics if the maximum value is less than the minimum value.

Examples

use rug::Rational;
let min = (-3, 2);
let max = (3, 2);
let too_small = Rational::from((-5, 2));
let r1 = too_small.clamp_ref(&min, &max);
let clamped1 = Rational::from(r1);
assert_eq!(clamped1, (-3, 2));
let in_range = Rational::from((1, 2));
let r2 = in_range.clamp_ref(&min, &max);
let clamped2 = Rational::from(r2);
assert_eq!(clamped2, (1, 2));

pub fn recip_ref(&self) -> RecipIncomplete

Computes the reciprocal.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

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

pub fn trunc_ref(&self) -> TruncIncomplete

Rounds the number towards zero.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Integer
• Assign<Src> for Rational
• From<Src> for Integer
• From<Src> for Rational

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

pub fn rem_trunc_ref(&self) -> RemTruncIncomplete

Computes the fractional part of the number.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

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

pub fn fract_trunc_ref(&self) -> FractTruncIncomplete

Computes the fractional and truncated parts of the number.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for (Rational, Integer)
• Assign<Src> for (&mut Rational, &mut Integer)
• From<Src> for (Rational, Integer)

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

pub fn ceil_ref(&self) -> CeilIncomplete

Rounds the number upwards (towards plus infinity).

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Integer
• Assign<Src> for Rational
• From<Src> for Integer
• From<Src> for Rational

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

pub fn rem_ceil_ref(&self) -> RemCeilIncomplete

Computes the non-positive remainder after rounding up.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

use rug::Rational;
// 100/17 = 6 − 2/17
let r = Rational::from((100, 17));
let r_ref = r.rem_ceil_ref();
let rem = Rational::from(r_ref);
assert_eq!(rem, (-2, 17));

pub fn fract_ceil_ref(&self) -> FractCeilIncomplete

Computes the fractional and ceil parts of the number.

The fractional part cannot be greater than zero.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for (Rational, Integer)
• Assign<Src> for (&mut Rational, &mut Integer)
• From<Src> for (Rational, Integer)

Examples

use rug::{Assign, Integer, Rational};
// 100/17 = 6 − 2/17
let r = Rational::from((100, 17));
let r_ref = r.fract_ceil_ref();
let (mut fract, mut ceil) = (Rational::new(), Integer::new());
(&mut fract, &mut ceil).assign(r_ref);
assert_eq!(fract, (-2, 17));
assert_eq!(ceil, 6);

pub fn floor_ref(&self) -> FloorIncomplete

Rounds the number downwards (towards minus infinity).

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Integer
• Assign<Src> for Rational
• From<Src> for Integer
• From<Src> for Rational

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

pub fn rem_floor_ref(&self) -> RemFloorIncomplete

Computes the non-negative remainder after rounding down.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

use rug::Rational;
// −100/17 = −6 + 2/17
let r = Rational::from((-100, 17));
let r_ref = r.rem_floor_ref();
let rem = Rational::from(r_ref);
assert_eq!(rem, (2, 17));

pub fn fract_floor_ref(&self) -> FractFloorIncomplete

Computes the fractional and floor parts of the number.

The fractional part cannot be negative.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for (Rational, Integer)
• Assign<Src> for (&mut Rational, &mut Integer)
• From<Src> for (Rational, Integer)

Examples

use rug::{Assign, Integer, Rational};
// −100/17 = −6 + 2/17
let r = Rational::from((-100, 17));
let r_ref = r.fract_floor_ref();
let (mut fract, mut floor) = (Rational::new(), Integer::new());
(&mut fract, &mut floor).assign(r_ref);
assert_eq!(fract, (2, 17));
assert_eq!(floor, -6);

pub fn round_ref(&self) -> RoundIncomplete

Rounds the number to the nearest integer.

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

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Integer
• Assign<Src> for Rational
• From<Src> for Integer
• From<Src> for Rational

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

pub fn rem_round_ref(&self) -> RemRoundIncomplete

Computes the remainder after rounding to the nearest integer.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

use rug::Rational;
// −3.5 = −4 + 0.5 = −4 + 1/2
let r1 = Rational::from((-35, 10));
let r_ref1 = r1.rem_round_ref();
let rem1 = Rational::from(r_ref1);
assert_eq!(rem1, (1, 2));
// 3.7 = 4 − 0.3 = 4 − 3/10
let r2 = Rational::from((37, 10));
let r_ref2 = r2.rem_round_ref();
let rem2 = Rational::from(r_ref2);
assert_eq!(rem2, (-3, 10));

pub fn fract_round_ref(&self) -> FractRoundIncomplete

Computes the fractional and round parts of the number.

The fractional part is positive when the number is rounded down and negative when the number is rounded up. When the number lies exactly between two integers, it is rounded away from zero.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for (Rational, Integer)
• Assign<Src> for (&mut Rational, &mut Integer)
• From<Src> for (Rational, Integer)

Examples

use rug::{Assign, Integer, Rational};
// −3.5 = −4 + 0.5 = −4 + 1/2
let r1 = Rational::from((-35, 10));
let r_ref1 = r1.fract_round_ref();
let (mut fract1, mut round1) = (Rational::new(), Integer::new());
(&mut fract1, &mut round1).assign(r_ref1);
assert_eq!(fract1, (1, 2));
assert_eq!(round1, -4);
// 3.7 = 4 − 0.3 = 4 − 3/10
let r2 = Rational::from((37, 10));
let r_ref2 = r2.fract_round_ref();
let (mut fract2, mut round2) = (Rational::new(), Integer::new());
(&mut fract2, &mut round2).assign(r_ref2);
assert_eq!(fract2, (-3, 10));
assert_eq!(round2, 4);

pub fn square_ref(&self) -> SquareIncomplete

Computes the square.

The following are implemented with the returned incomplete-computation value as Src:

• Assign<Src> for Rational
• From<Src> for Rational

Examples

use rug::Rational;
let r = Rational::from((-13, 2));
assert_eq!(Rational::from(r.square_ref()), (169, 4));

Trait Implementations

impl<'_> Assign<&'_ SmallRational> for SmallRational

fn assign(&mut self, other: &Self)

Peforms the assignement.

impl<Num: ToSmall, Den: ToSmall> Assign<(Num, Den)> for SmallRational

fn assign(&mut self, src: (Num, Den))

Peforms the assignement.

impl<Num: ToSmall> Assign<Num> for SmallRational

fn assign(&mut self, src: Num)

Peforms the assignement.

impl Assign<SmallRational> for SmallRational

fn assign(&mut self, other: Self)

Peforms the assignement.

impl Clone for SmallRational

fn clone(&self) -> SmallRational

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for SmallRational

fn default() -> Self

Returns the "default value" for a type.

impl Deref for SmallRational

type Target = Rational

The resulting type after dereferencing.

fn deref(&self) -> &Rational

Dereferences the value.

impl<Num: ToSmall, Den: ToSmall> From<(Num, Den)> for SmallRational

fn from(src: (Num, Den)) -> Self

Performs the conversion.

impl<Num: ToSmall> From<Num> for SmallRational

fn from(src: Num) -> Self

Performs the conversion.

impl Send for SmallRational