#[repr(transparent)]
pub struct BorrowRational<'a> { /* private fields */ }
Expand description

Used to get a reference to a Rational number.

The struct implements Deref<Target = Rational>.

No memory is unallocated when this struct is dropped.

Examples

use rug::rational::BorrowRational;
use rug::Rational;
let r = Rational::from((42, 3));
let neg: BorrowRational = r.as_neg();
// r is still valid
assert_eq!(r, (42, 3));
assert_eq!(*neg, (-42, 3));

Implementations§

source§

impl<'a> BorrowRational<'a>

source

pub const unsafe fn from_raw(raw: mpq_t) -> BorrowRational<'a>

Create a borrow from a raw GMP rational number.

Safety
  • The value must be initialized as a valid mpq_t.
  • The mpq_t type can be considered as a kind of pointer, so there can be multiple copies of it. BorrowRational cannot mutate the value, so there can be other copies, but none of them are allowed to mutate the value.
  • The lifetime is obtained from the return type. The user must ensure the value remains valid for the duration of the lifetime.
  • The numerator and denominator must be in canonical form, as the rest of the library assumes that they are. Most GMP functions leave the rational number in canonical form, but assignment functions do not. Check the GMP documentation for details.
Examples
use rug::rational::BorrowRational;
use rug::Rational;
let r = Rational::from((42, 3));
// Safety: r.as_raw() is a valid pointer.
let raw = unsafe { *r.as_raw() };
// Safety: r is still valid when borrow is used.
let borrow = unsafe { BorrowRational::from_raw(raw) };
assert_eq!(r, *borrow);
source

pub const fn const_deref<'b>(b: &'b BorrowRational<'a>) -> &'b Rational

Gets a reference to Rational from a BorrowRational.

This is equivalent to taking the reference of the dereferencing operator * or to Deref::deref, but can also be used in constant context. Unless required in constant context, use the operator or trait instead.

Planned deprecation

This method will be deprecated when the unary * operator and the Deref trait are usable in constant context.

Examples
use core::ops::Deref;
use core::ptr;
use rug::rational::BorrowRational;
use rug::Rational;

let i = Rational::from((-5, 7));
let b = i.as_recip();
let using_method: &Rational = BorrowRational::const_deref(&b);
let using_operator: &Rational = &*b;
let using_trait: &Rational = b.deref();
assert_eq!(*using_trait, (-7, 5));
assert!(ptr::eq(using_method, using_operator));
assert!(ptr::eq(using_method, using_trait));

This method can be used to create a constant reference.

use gmp_mpfr_sys::gmp;
use gmp_mpfr_sys::gmp::{limb_t, mpq_t};
use rug::rational::BorrowRational;
use rug::{Integer, Rational};

const NUMER_LIMBS: [limb_t; 2] = [0, 5];
const DENOM_LIMBS: [limb_t; 1] = [3];
const MPQ: mpq_t = unsafe {
    mpq_t {
        num: gmp::MPZ_ROINIT_N(NUMER_LIMBS.as_ptr().cast_mut(), -2),
        den: gmp::MPZ_ROINIT_N(DENOM_LIMBS.as_ptr().cast_mut(), 1),
    }
};
// Safety: MPQ will remain valid, and will not be changed.
const BORROW: BorrowRational = unsafe { BorrowRational::from_raw(MPQ) };
const R: &Rational = BorrowRational::const_deref(&BORROW);
let numer_check =
    -((Integer::from(NUMER_LIMBS[1]) << gmp::NUMB_BITS) + NUMER_LIMBS[0]);
let denom_check = Integer::from(DENOM_LIMBS[0]);
let check = Rational::from((&numer_check, &denom_check));
assert_eq!(*R, check);
assert_eq!(*R.numer(), *check.numer());
assert_eq!(*R.denom(), *check.denom());

Methods from Deref<Target = Rational>§

source

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

pub fn to_f32(&self) -> f32

Converts to an f32, rounding towards zero.

This conversion can also be performed using

Examples
use rug::rational::SmallRational;
use rug::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);
source

pub fn to_f64(&self) -> f64

Converts to an f64, rounding towards zero.

This conversion can also be performed using

Examples
use rug::rational::SmallRational;
use rug::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);
source

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

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

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

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

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

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

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

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

pub fn is_integer(&self) -> bool

Returns true if the number is an integer.

Examples
use rug::Rational;
assert!(!(Rational::from((5, 2)).is_integer()));
assert!(Rational::from(3).is_integer());
source

pub fn abs_ref(&self) -> AbsIncomplete<'_>

Computes the absolute value.

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

Examples
use rug::{Complete, Rational};
let r = Rational::from((-100, 17));
let abs = r.abs_ref().complete();
assert_eq!(abs, (100, 17));
source

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:

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

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:

Panics

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

Examples
use rug::{Assign, Complete, Rational};
let min = (-3, 2);
let max = (3, 2);
let too_small = Rational::from((-5, 2));
let mut clamped = too_small.clamp_ref(&min, &max).complete();
assert_eq!(clamped, (-3, 2));
let in_range = Rational::from((1, 2));
clamped.assign(in_range.clamp_ref(&min, &max));
assert_eq!(clamped, (1, 2));
source

pub fn recip_ref(&self) -> RecipIncomplete<'_>

Computes the reciprocal.

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

Examples
use rug::{Complete, Rational};
let r = Rational::from((-100, 17));
assert_eq!(r.recip_ref().complete(), (-17, 100));
source

pub fn trunc_ref(&self) -> TruncIncomplete<'_>

Rounds the number towards zero.

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

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

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:

Examples
use rug::{Complete, Rational};
// -100/17 = -5 - 15/17
let r = Rational::from((-100, 17));
assert_eq!(r.rem_trunc_ref().complete(), (-15, 17));
source

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:

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

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:

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

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:

Examples
use rug::{Complete, Rational};
// 100/17 = 6 - 2/17
let r = Rational::from((100, 17));
assert_eq!(r.rem_ceil_ref().complete(), (-2, 17));
source

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:

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

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:

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

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:

Examples
use rug::{Complete, Rational};
// -100/17 = -6 + 2/17
let r = Rational::from((-100, 17));
assert_eq!(r.rem_floor_ref().complete(), (2, 17));
source

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:

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

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:

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

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:

Examples
use rug::{Assign, Complete, Rational};
// -3.5 = -4 + 0.5 = -4 + 1/2
let r1 = Rational::from((-35, 10));
let mut rem = r1.rem_round_ref().complete();
assert_eq!(rem, (1, 2));
// 3.7 = 4 - 0.3 = 4 - 3/10
let r2 = Rational::from((37, 10));
rem.assign(r2.rem_round_ref());
assert_eq!(rem, (-3, 10));
source

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:

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

pub fn square_ref(&self) -> MulIncomplete<'_>

Computes the square.

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

r.square_ref() produces the exact same result as &r * &r.

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

Trait Implementations§

source§

impl Binary for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.
source§

impl<'a> Clone for BorrowRational<'a>

source§

fn clone(&self) -> BorrowRational<'a>

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter. Read more
source§

impl Deref for BorrowRational<'_>

§

type Target = Rational

The resulting type after dereferencing.
source§

fn deref(&self) -> &Rational

Dereferences the value.
source§

impl Display for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter. Read more
source§

impl LowerHex for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.
source§

impl Octal for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.
source§

impl Pointer for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.
source§

impl UpperHex for BorrowRational<'_>

source§

fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.
source§

impl<'a> Copy for BorrowRational<'a>

source§

impl Send for BorrowRational<'_>

source§

impl Sync for BorrowRational<'_>

Auto Trait Implementations§

§

impl<'a> RefUnwindSafe for BorrowRational<'a>

§

impl<'a> Unpin for BorrowRational<'a>

§

impl<'a> UnwindSafe for BorrowRational<'a>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Az for T

source§

fn az<Dst>(self) -> Dstwhere T: Cast<Dst>,

Casts the value.
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<Src, Dst> CastFrom<Src> for Dstwhere Src: Cast<Dst>,

source§

fn cast_from(src: Src) -> Dst

Casts the value.
source§

impl<T> CheckedAs for T

source§

fn checked_as<Dst>(self) -> Option<Dst>where T: CheckedCast<Dst>,

Casts the value.
source§

impl<Src, Dst> CheckedCastFrom<Src> for Dstwhere Src: CheckedCast<Dst>,

source§

fn checked_cast_from(src: Src) -> Option<Dst>

Casts the value.
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> OverflowingAs for T

source§

fn overflowing_as<Dst>(self) -> (Dst, bool)where T: OverflowingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> OverflowingCastFrom<Src> for Dstwhere Src: OverflowingCast<Dst>,

source§

fn overflowing_cast_from(src: Src) -> (Dst, bool)

Casts the value.
source§

impl<T> SaturatingAs for T

source§

fn saturating_as<Dst>(self) -> Dstwhere T: SaturatingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> SaturatingCastFrom<Src> for Dstwhere Src: SaturatingCast<Dst>,

source§

fn saturating_cast_from(src: Src) -> Dst

Casts the value.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> UnwrappedAs for T

source§

fn unwrapped_as<Dst>(self) -> Dstwhere T: UnwrappedCast<Dst>,

Casts the value.
source§

impl<Src, Dst> UnwrappedCastFrom<Src> for Dstwhere Src: UnwrappedCast<Dst>,

source§

fn unwrapped_cast_from(src: Src) -> Dst

Casts the value.
source§

impl<T> WrappingAs for T

source§

fn wrapping_as<Dst>(self) -> Dstwhere T: WrappingCast<Dst>,

Casts the value.
source§

impl<Src, Dst> WrappingCastFrom<Src> for Dstwhere Src: WrappingCast<Dst>,

source§

fn wrapping_cast_from(src: Src) -> Dst

Casts the value.