Struct rug::rational::MiniRational

pub struct MiniRational { /* private fields */ }

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 MiniRational does require some computation, as the numerator and denominator need to be canonicalized.

The borrow method returns an object that can be coerced to a Rational, as it implements Deref<Target = Rational>.

Examples

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

Implementations

impl MiniRational

pub const fn new() -> Self

Creates a MiniRational with value 0.

Examples

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

pub const fn const_from_integer(val: MiniInteger) -> Self

Creates a MiniRational from a MiniInteger.

This is equivalent to MiniRational::from(val), but can also be used in constant context. Unless required in constant context, use the From trait instead.

Planned deprecation

This method will be deprecated when the From trait is usable in constant context.

Examples

use rug::integer::MiniInteger;
use rug::rational::{BorrowRational, MiniRational};
use rug::Rational;

const TWO_INT: MiniInteger = MiniInteger::const_from_i8(2i8);
const TWO_MINI: MiniRational = MiniRational::const_from_integer(TWO_INT);
const TWO_BORROW: BorrowRational = TWO_MINI.borrow();
const TWO: &Rational = BorrowRational::const_deref(&TWO_BORROW);
assert_eq!(*TWO, 2);

const HALF_BORROW: BorrowRational = TWO.as_recip();
const HALF: &Rational = BorrowRational::const_deref(&HALF_BORROW);
assert_eq!(*HALF, MiniRational::from((1, 2)));

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::MiniRational;
let mut r = MiniRational::from((-15i32, 47i32));
let (num_capacity, den_capacity) = {
    let b = r.borrow();
    (b.numer().capacity(), b.denom().capacity())
};
// reciprocating this will not require reallocations
unsafe {
    r.as_nonreallocating_rational().recip_mut();
}
let after = r.borrow();
assert_eq!(*after, MiniRational::from((-47, 15)));
assert_eq!(after.numer().capacity(), num_capacity);
assert_eq!(after.denom().capacity(), den_capacity);

pub const fn borrow(&self) -> BorrowRational<'_>

Borrows the rational number.

The returned object implements Deref<Target = Rational>.

The borrow lasts until the returned object exits scope. Multiple borrows can be taken at the same time.

Examples

use rug::rational::MiniRational;
use rug::Rational;
let r = MiniRational::from((-13i32, 5i32));
let b = r.borrow();
let abs_ref = Rational::from(b.abs_ref());
assert_eq!(*abs_ref.numer(), 13);
assert_eq!(*abs_ref.denom(), 5);

pub fn borrow_excl(&mut self) -> &Rational

Borrows the rational number exclusively.

This is similar to the borrow method, but it requires exclusive access to the underlying MiniRational; the returned reference can however be shared. The exclusive access is required to reduce the amount of housekeeping necessary, providing a more efficient operation.

Examples

use rug::rational::MiniRational;
use rug::Rational;
let mut r = MiniRational::from((-13i32, 5i32));
let b = r.borrow_excl();
let abs_ref = Rational::from(b.abs_ref());
assert_eq!(*abs_ref.numer(), 13);
assert_eq!(*abs_ref.denom(), 5);

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

Creates a MiniRational 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::MiniRational;
let from_unsafe = unsafe { MiniRational::from_canonical(-13, 10) };
// from_safe is canonicalized to the same form as from_unsafe
let from_safe = MiniRational::from((130, -100));
let unsafe_borrow = from_unsafe.borrow();
let safe_borrow = from_safe.borrow();
assert_eq!(unsafe_borrow.numer(), safe_borrow.numer());
assert_eq!(unsafe_borrow.denom(), safe_borrow.denom());

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

Assigns a numerator and denominator to a MiniRational, 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::MiniRational;
use rug::Assign;
let mut a = MiniRational::new();
unsafe {
    a.assign_canonical(-13, 10);
}
// b is canonicalized to the same form as a
let mut b = MiniRational::new();
b.assign((130, -100));
let a_borrow = a.borrow();
let b_borrow = b.borrow();
assert_eq!(a_borrow.numer(), b_borrow.numer());
assert_eq!(a_borrow.denom(), b_borrow.denom());

Trait Implementations

impl Assign<&MiniRational> for MiniRational

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

Peforms the assignement.

impl Assign<&MiniRational> for Rational

fn assign(&mut self, src: &MiniRational)

Peforms the assignement.

impl<Num: ToMini, Den: ToMini> Assign<(Num, Den)> for MiniRational

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

Peforms the assignement.

impl Assign<MiniInteger> for MiniRational

fn assign(&mut self, src: MiniInteger)

Peforms the assignement.

impl Assign<MiniRational> for Rational

fn assign(&mut self, src: MiniRational)

Peforms the assignement.

impl<Num: ToMini> Assign<Num> for MiniRational

fn assign(&mut self, src: Num)

Peforms the assignement.

impl Assign for MiniRational

fn assign(&mut self, other: Self)

Peforms the assignement.

impl Binary for MiniRational

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

Formats the value using the given formatter.

impl Clone for MiniRational

fn clone(&self) -> MiniRational

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MiniRational

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

Formats the value using the given formatter.

impl Default for MiniRational

fn default() -> Self

Returns the “default value” for a type.

impl Display for MiniRational

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

Formats the value using the given formatter.

impl From<&MiniRational> for Rational

fn from(src: &MiniRational) -> Self

Converts to this type from the input type.

impl<Num: ToMini, Den: ToMini> From<(Num, Den)> for MiniRational

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

Converts to this type from the input type.

impl From<MiniInteger> for MiniRational

fn from(src: MiniInteger) -> Self

Converts to this type from the input type.

impl From<MiniRational> for Rational

fn from(src: MiniRational) -> Self

Converts to this type from the input type.

impl<Num: ToMini> From<Num> for MiniRational

fn from(src: Num) -> Self

Converts to this type from the input type.

impl LowerHex for MiniRational

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

Formats the value using the given formatter.

impl Octal for MiniRational

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

Formats the value using the given formatter.

impl PartialEq<MiniRational> for Rational

fn eq(&self, other: &MiniRational) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Rational> for MiniRational

fn eq(&self, other: &Rational) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<MiniRational> for Rational

fn partial_cmp(&self, other: &MiniRational) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Rational> for MiniRational

fn partial_cmp(&self, other: &Rational) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl UpperHex for MiniRational

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

Formats the value using the given formatter.

impl Copy for MiniRational

impl Send for MiniRational

impl Sync for MiniRational