Struct figures::Fraction

#[repr(C)]
pub struct Fraction { /* private fields */ }

A fraction type for predictable integer-based math.

Internally this type uses 32 bits of data to represent a fraction:

• 1 bit of data for the positive/negative sign.
• 15 bits of data for the numerator
• 16 bits of data for the denominator

Many math operations are performed using temporary 32-bit values for the fraction, simplifing at the end of the operation. This prevents overflows, but does not prevent precision loss. We can see this by purposely buliding fractions that are hard to represent:

use figures::fraction;

assert_eq!(
    fraction!(1 / 32719) + fraction!(1 / 32749),
    fraction!(2 / 32749)
);

The above example adds fractions that have denominators using two largest primes that fit in 16 bits. The result should be 65,468/1,071,514,531, but that denominator is clearly too large. Because the fractions being added had prime numbers for their denominators, there is no way to reduce this fraction without losing information. For this particular example, a precision loss of ~2.8e-8 occurs.

However, in 2d graphics programming, it’s rare to be working with irrational numbers outside of angles represented in radians.

Implementations

impl Fraction

pub const MAX: Self = _

The maximum value representable by this type.

pub const MIN: Self = _

The minimum value representable by this type.

pub const ONE: Self = _

A fraction equivalent to 1.

pub const PI: Self = _

A fractional approximation of Pi, accurate to within 2.67e-7.

pub const ZERO: Self = _

A fraction equivalent to 0.

pub const fn new_whole(whole_number: i16) -> Self

Returns a new fraction for a whole number.

pub fn new(numerator: i16, denominator: i16) -> Self

Returns a new fraction using the components provided.

denominator will be limited to the absolute value of i16::MIN.

pub const fn numerator(&self) -> i16

Returns the numerator of the fraction.

pub const fn denominator(&self) -> i16

Returns the denominator of the fraction.

pub const fn is_positive(&self) -> bool

Returns true if the fraction is positive (greater than zero).

Note: Zero is neither negative nor positive.

pub const fn is_zero(&self) -> bool

Returns true if the fraction is zero.

pub const fn is_negative(&self) -> bool

Returns true if the fraction is negative (less than zero).

Note: Zero is neither negative nor positive.

pub fn into_compound(self) -> (i16, Fraction)

Simplifies the fraction into a compound number.

use figures::Fraction;

assert_eq!(
    Fraction::new(1, 3).into_compound(),
    (0, Fraction::new(1, 3))
);
assert_eq!(
    Fraction::new(4, 3).into_compound(),
    (1, Fraction::new(1, 3))
);
assert_eq!(
    Fraction::new(-4, 3).into_compound(),
    (-1, Fraction::new(-1, 3))
);

Adding the number and the fraction back together will result in the original fraction.

use figures::Fraction;

let improper = Fraction::new(-4, 3);
let (whole, fraction) = improper.into_compound();
assert_eq!(Fraction::from(whole) + fraction, improper);

pub fn round(self) -> i16

Rounds this fraction to the nearest whole number.

pub fn round_with_amount(self) -> (i16, Fraction)

Rounds this fraction to the nearest whole number, returning the fractional component that was rounded away. This fraction can be added to the whole number to reconstruct the original fraction.

use figures::Fraction;

let (whole, fraction) = Fraction::new(5, 3).round_with_amount();
assert_eq!(whole, 2);
assert_eq!(fraction, Fraction::new(-1, 3));
assert_eq!(Fraction::new_whole(whole) + fraction, Fraction::new(5, 3));

let (whole, fraction) = Fraction::new(-5, 3).round_with_amount();
assert_eq!(whole, -2);
assert_eq!(fraction, Fraction::new(1, 3));
assert_eq!(Fraction::new_whole(whole) + fraction, Fraction::new(-5, 3));

pub fn into_f32(self) -> f32

Returns this fraction as a floating point number.

pub const fn inverse(self) -> Self

Returns the inverse of this fraction.

pub const fn abs(self) -> Self

Returns the absolute value of this fraction.

pub fn atan(self) -> Angle

Returns the arctangent of this fraction.

This function is implemented using a lookup table and is an approximation.

pub fn atan2(self, other: Self) -> Angle

Returns the result of arctan(self/other) while correctly handling negative numbers.

Trait Implementations

impl Add<f32> for Fraction

type Output = Fraction

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Self::Output

Performs the + operation.

impl Add<i16> for Fraction

type Output = Fraction

The resulting type after applying the + operator.

fn add(self, rhs: i16) -> Self::Output

Performs the + operation.

impl Add for Fraction

type Output = Fraction

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl AddAssign<f32> for Fraction

fn add_assign(&mut self, rhs: f32)

Performs the += operation.

impl AddAssign<i16> for Fraction

fn add_assign(&mut self, rhs: i16)

Performs the += operation.

impl AddAssign for Fraction

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl Clone for Fraction

fn clone(&self) -> Fraction

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Fraction

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Fraction

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Fraction

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

Formats the value using the given formatter.

impl Div<Fraction> for Lp

type Output = Lp

The resulting type after applying the / operator.

fn div(self, rhs: Fraction) -> Self::Output

Performs the / operation.

impl Div<Fraction> for Px

type Output = Px

The resulting type after applying the / operator.

fn div(self, rhs: Fraction) -> Self::Output

Performs the / operation.

impl Div<Fraction> for UPx

type Output = UPx

The resulting type after applying the / operator.

fn div(self, rhs: Fraction) -> Self::Output

Performs the / operation.

impl Div<Fraction> for i32

type Output = i32

The resulting type after applying the / operator.

fn div(self, rhs: Fraction) -> Self::Output

Performs the / operation.

impl Div<Fraction> for u32

type Output = u32

The resulting type after applying the / operator.

fn div(self, rhs: Fraction) -> Self::Output

Performs the / operation.

impl Div<f32> for Fraction

type Output = Fraction

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Self::Output

Performs the / operation.

impl Div<i16> for Fraction

type Output = Fraction

The resulting type after applying the / operator.

fn div(self, rhs: i16) -> Self::Output

Performs the / operation.

impl Div for Fraction

type Output = Fraction

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl DivAssign<f32> for Fraction

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl DivAssign<i16> for Fraction

fn div_assign(&mut self, rhs: i16)

Performs the /= operation.

impl DivAssign for Fraction

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl From<Fraction> for Angle

fn from(value: Fraction) -> Self

Converts to this type from the input type.

impl From<Fraction> for f32

fn from(value: Fraction) -> Self

Converts to this type from the input type.

impl From<f32> for Fraction

fn from(scale: f32) -> Self

Converts to this type from the input type.

impl From<i16> for Fraction

fn from(numerator: i16) -> Self

Converts to this type from the input type.

impl Hash for Fraction

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<Fraction> for Lp

type Output = Lp

The resulting type after applying the * operator.

fn mul(self, rhs: Fraction) -> Self::Output

Performs the * operation.

impl Mul<Fraction> for Px

type Output = Px

The resulting type after applying the * operator.

fn mul(self, rhs: Fraction) -> Self::Output

Performs the * operation.

impl Mul<Fraction> for UPx

type Output = UPx

The resulting type after applying the * operator.

fn mul(self, rhs: Fraction) -> Self::Output

Performs the * operation.

impl Mul<Fraction> for i32

type Output = i32

The resulting type after applying the * operator.

fn mul(self, rhs: Fraction) -> Self::Output

Performs the * operation.

impl Mul<Fraction> for u32

type Output = u32

The resulting type after applying the * operator.

fn mul(self, rhs: Fraction) -> Self::Output

Performs the * operation.

impl Mul<f32> for Fraction

type Output = Fraction

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self::Output

Performs the * operation.

impl Mul<i16> for Fraction

type Output = Fraction

The resulting type after applying the * operator.

fn mul(self, rhs: i16) -> Self::Output

Performs the * operation.

impl Mul for Fraction

type Output = Fraction

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl MulAssign<f32> for Fraction

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl MulAssign<i16> for Fraction

fn mul_assign(&mut self, rhs: i16)

Performs the *= operation.

impl MulAssign for Fraction

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl Neg for Fraction

type Output = Fraction

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Ord for Fraction

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Fraction

fn eq(&self, other: &Fraction) -> 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 for Fraction

fn partial_cmp(&self, other: &Self) -> 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 Serialize for Fraction

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<f32> for Fraction

type Output = Fraction

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Self::Output

Performs the - operation.

impl Sub<i16> for Fraction

type Output = Fraction

The resulting type after applying the - operator.

fn sub(self, rhs: i16) -> Self::Output

Performs the - operation.

impl Sub for Fraction

type Output = Fraction

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl SubAssign<f32> for Fraction

fn sub_assign(&mut self, rhs: f32)

Performs the -= operation.

impl SubAssign<i16> for Fraction

fn sub_assign(&mut self, rhs: i16)

Performs the -= operation.

impl SubAssign for Fraction

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl TryFrom<i128> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: i128) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i32> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: i32) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<i64> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: i64) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<isize> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: isize) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u128> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: u128) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u16> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: u16) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u32> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: u32) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<u64> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: u64) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<usize> for Fraction

type Error = TryFromIntError

The type returned in the event of a conversion error.

fn try_from(value: usize) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Fraction

impl Eq for Fraction

impl StructuralEq for Fraction

impl StructuralPartialEq for Fraction