Struct rug::rational::SmallRational
source · pub struct SmallRational { /* private fields */ }
Expand description
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;
use rug::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);
Implementations§
source§impl SmallRational
impl SmallRational
sourcepub const fn new() -> Self
pub const 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);
sourcepub unsafe fn as_nonreallocating_rational(&mut self) -> &mut Rational
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 behavior 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 behavior.
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);
sourcepub unsafe fn from_canonical<Num: ToSmall, Den: ToSmall>(
num: Num,
den: Den
) -> Self
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 behavior 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());
sourcepub unsafe fn assign_canonical<Num: ToSmall, Den: ToSmall>(
&mut self,
num: Num,
den: Den
)
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 behavior if den
is zero or negative, or
if num
and den
have common factors.
Examples
use rug::rational::SmallRational;
use rug::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 const ZERO: &Rational = _
pub const ONE: &Rational = _
pub const NEG_ONE: &Rational = _
sourcepub fn as_raw(&self) -> *const mpq_t
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));
sourcepub fn to_f32(&self) -> f32
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);
sourcepub fn to_f64(&self) -> f64
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);
sourcepub fn to_string_radix(&self, radix: i32) -> String
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");
sourcepub fn as_neg(&self) -> BorrowRational<'_>
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);
sourcepub fn as_abs(&self) -> BorrowRational<'_>
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);
sourcepub fn as_recip(&self) -> BorrowRational<'_>
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);
sourcepub fn is_positive(&self) -> bool
pub fn is_positive(&self) -> bool
sourcepub fn is_negative(&self) -> bool
pub fn is_negative(&self) -> bool
sourcepub fn cmp_abs(&self, other: &Self) -> Ordering
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);
sourcepub fn is_integer(&self) -> bool
pub fn is_integer(&self) -> bool
sourcepub fn abs_ref(&self) -> AbsIncomplete<'_>
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));
sourcepub fn signum_ref(&self) -> SignumIncomplete<'_>
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
Complete<Completed = Rational> for 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);
sourcepub 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>,
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));
sourcepub fn recip_ref(&self) -> RecipIncomplete<'_>
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));
sourcepub fn trunc_ref(&self) -> TruncIncomplete<'_>
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
Complete<Completed = Rational> for 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);
sourcepub fn rem_trunc_ref(&self) -> RemTruncIncomplete<'_>
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));
sourcepub fn fract_trunc_ref(&self) -> FractTruncIncomplete<'_>
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)
Complete<Completed = (Rational, Integer)> for 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);
sourcepub fn ceil_ref(&self) -> CeilIncomplete<'_>
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
Complete<Completed = Rational> for 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);
sourcepub fn rem_ceil_ref(&self) -> RemCeilIncomplete<'_>
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));
sourcepub fn fract_ceil_ref(&self) -> FractCeilIncomplete<'_>
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)
Complete<Completed = (Rational, Integer)> for 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);
sourcepub fn floor_ref(&self) -> FloorIncomplete<'_>
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
Complete<Completed = Rational> for 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);
sourcepub fn rem_floor_ref(&self) -> RemFloorIncomplete<'_>
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));
sourcepub fn fract_floor_ref(&self) -> FractFloorIncomplete<'_>
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)
Complete<Completed = (Rational, Integer)> for 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);
sourcepub fn round_ref(&self) -> RoundIncomplete<'_>
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
Complete<Completed = Rational> for 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);
sourcepub fn rem_round_ref(&self) -> RemRoundIncomplete<'_>
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));
sourcepub fn fract_round_ref(&self) -> FractRoundIncomplete<'_>
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)
Complete<Completed = (Rational, Integer)> for 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);
sourcepub fn square_ref(&self) -> MulIncomplete<'_>
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 Assign<&SmallRational> for SmallRational
impl Assign<&SmallRational> for SmallRational
source§impl<Num: ToSmall, Den: ToSmall> Assign<(Num, Den)> for SmallRational
impl<Num: ToSmall, Den: ToSmall> Assign<(Num, Den)> for SmallRational
source§fn assign(&mut self, src: (Num, Den))
fn assign(&mut self, src: (Num, Den))
source§impl<Num: ToSmall> Assign<Num> for SmallRational
impl<Num: ToSmall> Assign<Num> for SmallRational
source§impl Assign<SmallRational> for SmallRational
impl Assign<SmallRational> for SmallRational
source§impl Clone for SmallRational
impl Clone for SmallRational
source§fn clone(&self) -> SmallRational
fn clone(&self) -> SmallRational
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more