Struct I128

pub struct I128<const BITS: u32, const SHIFT: i32>(/* private fields */);

#[repr(transparent)] struct containing i128 interpreted as a fixed-point number.

Implements the trait fp::Num for fixed-point manipulation.

Implementations

impl<const B: u32, const S: i32> I128<B, S>

pub unsafe fn into_unsigned_unchecked(self) -> U128<{ _ }, S>

where [(); { _ }]:,

pub fn into_unsigned(self) -> Option<U128<{ _ }, S>>

where [(); { _ }]:,

Trait Implementations

impl<const B0: u32, const B1: u32, const S: i32> Add<I128<B1, S>> for I128<B0, S>

where [(); { _ }]:,

Two fixed-point integers with the same raw type and the same shift may be added together. The result has the same raw type and the same shift. The result has 1 more bit than the number of bits in the wider of the two inputs.

type Output = I128<{ max(B0, B1) + 1 }, S>

The resulting type after applying the + operator.

fn add(self: I128<B0, S>, other: I128<B1, S>) -> Self::Output

Performs the + operation.

impl<const BITS: u32, const SHIFT: i32> Clone for I128<BITS, SHIFT>

fn clone(&self) -> I128<BITS, SHIFT>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const BITS: u32, const SHIFT: i32> Debug for I128<BITS, SHIFT>

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

Formats the value using the given formatter.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Div<I128<B1, S1>> for I128<B0, S0>

where [(); { _ }]:,

type Output = I128<{ B0 + Self::SIGNED as u32 }, { S0 - S1 }>

The resulting type after applying the / operator.

fn div(self: I128<B0, S0>, other: I128<B1, S1>) -> Self::Output

Performs the / operation.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Div<I128<B1, S1>> for U128<B0, S0>

where [(); { _ }]:,

type Output = I128<{ B0 + 1 }, { S0 - S1 }>

The resulting type after applying the / operator.

fn div(self: U128<B0, S0>, other: I128<B1, S1>) -> Self::Output

Performs the / operation.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Div<U128<B1, S1>> for I128<B0, S0>

where [(); { _ }]:,

type Output = I128<B0, { S0 - S1 }>

The resulting type after applying the / operator.

fn div(self: I128<B0, S0>, other: U128<B1, S1>) -> Self::Output

Performs the / operation.

impl From<I128<{ <$T>::BITS }, 0>> for i128

i128 is the same as I128<i128::BITS, 0>.

fn from(val: I128<{ i128::BITS }, 0>) -> Self

Converts to this type from the input type.

impl<const BITS: u32, const SHIFT: i32> From<I128<BITS, SHIFT>> for f32

fn from(val: I128<BITS, SHIFT>) -> f32

Converts to this type from the input type.

impl<const BITS: u32, const SHIFT: i32> From<I128<BITS, SHIFT>> for f64

fn from(val: I128<BITS, SHIFT>) -> f64

Converts to this type from the input type.

impl From<i128> for I128<{ i128::BITS }, 0>

i128 is the same as I128<i128::BITS, 0>.

fn from(val: i128) -> Self

Converts to this type from the input type.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Mul<I128<B1, S1>> for I128<B0, S0>

where [(); { _ }]:,

type Output = I128<{ B0 + B1 }, { S0 + S1 }>

The resulting type after applying the * operator.

fn mul(self: I128<B0, S0>, other: I128<B1, S1>) -> Self::Output

Performs the * operation.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Mul<I128<B1, S1>> for U128<B0, S0>

where [(); { _ }]:,

type Output = I128<{ B0 + B1 }, { S0 + S1 }>

The resulting type after applying the * operator.

fn mul(self: U128<B0, S0>, other: I128<B1, S1>) -> Self::Output

Performs the * operation.

impl<const B0: u32, const B1: u32, const S0: i32, const S1: i32> Mul<U128<B1, S1>> for I128<B0, S0>

where [(); { _ }]:,

type Output = I128<{ B0 + B1 }, { S0 + S1 }>

The resulting type after applying the * operator.

fn mul(self: I128<B0, S0>, other: U128<B1, S1>) -> Self::Output

Performs the * operation.

impl<const B: u32, const S: i32> Neg for I128<B, S>

where [(); { _ }]:,

Any fixed-point integer may be negated. The result of negation is always signed. Negation adds a bit: unsigned values gain a sign bit; signed values can overflow from MIN to -MIN = MAX + 1. The shift is unchanged.

type Output = I128<{ B + 1 }, S>

The resulting type after applying the - operator.

fn neg(self: I128<B, S>) -> Self::Output

Performs the unary - operation.

impl<const BITS: u32, const SHIFT: i32> Num for I128<BITS, SHIFT>

unsafe fn from_f32_unchecked(val: f32) -> Self

The caller must ensure that val is within the range of this fixed-point type, and that the quantity val / 2_f32.powi(-SHIFT) is finite.

unsafe fn from_f64_unchecked(val: f64) -> Self

The caller must ensure that val is within the range of this fixed-point type, and that the quantity val / 2_f64.powi(-SHIFT) is finite.

fn into_f32(self) -> f32

Conversion to f32 is guaranteed to be exact. Therefore, this function requires BITS <= 24 (to prevent truncation), SHIFT <= 149 (to prevent underflow), and BITS - SHIFT <= 128 (to prevent overflow).

For fixed-point numbers which do not meet these requirements, use raw_shr() to reduce the number of bits and logical_shr() to adjust the shift as needed.

fn into_f64(self) -> f64

Conversion to f64 is guaranteed to be exact. Therefore, this function requires BITS <= 53 (to prevent truncation), SHIFT <= 1074 (to prevent underflow), and BITS - SHIFT <= 1024 (to prevent overflow).

For fixed-point numbers which do not meet these requirements, use raw_shr() to reduce the number of bits and logical_shr() to adjust the shift as needed.

const BITS: u32

BITS is the number of least-significant bits which are permitted to vary. The Raw::BITS - BITS high-order bits must be zero (for unsigned Raw) or the same as the high bit of the lower BITS bits (for signed Raw).

const SHIFT: i32 = SHIFT

SHIFT sets the scaling factor between the stored raw value (of type Raw) and the “logical” value with it represents. The logical value of this fixed-point number is equal to the raw value divided by 2.pow(SHIFT).

const MIN: Self

Minimum possible value of this type.

const MAX: Self

Maximum possible value of this type.

const SIGNED: bool = true

Whether this type is signed. (If false, it’s unsigned.)

type Raw = i128

The underlying (“raw”) representation of this fixed-point number. Typically this is a primitive integer type, e.g. i64.

type Output<const B: u32, const S: i32> = I128<B, S>

The type that this fixed point number will become after BITS and/or SHIFT are changed by an operation.

unsafe fn new_unchecked(val: i128) -> Self

Interpret the provided raw value as a fixed-point number of type Self. Unsafe: no bounds checking is performed; the caller must ensure that the result lies between Self::MIN and Self::MAX. It is almost always better to use .new().unwrap() instead of this function, so that an out-of-bounds value panics with a reasonable message instead of propagating undefined behavior.

fn raw(self) -> i128

Return the raw value which internally represents this fixed-point number.

fn new(val: Self::Raw) -> Result<Self, RangeError>

Interpret the provided raw value as a fixed-point number of type Self, or return a RangeError if it is too small or too large to represent a valid instance of Self.

fn from_f32(val: f32) -> Result<Self, RangeError>

Return the fixed-point number of type Self which has a logical value of val, or return a RangeError if val is too small or too large to be represented by Self.

fn from_f64(val: f64) -> Result<Self, RangeError>

Return the fixed-point number of type Self which has a logical value of val, or return a RangeError if val is too small or too large to be represented by Self.

fn from_fp<T: Num, F: Num<Raw = T>>(val: F) -> Self

where Self::Raw: TryFrom<T>,

Return the fixed-point number of type Self which has the same logical value as val. F and Self must have the same shift and signedness. Self must have at least as many bits as F.

fn into_fp<T, F: Num<Raw = T>>(self) -> F

where T: TryFrom<Self::Raw> + Num,

Return the fixed-point number of type F which has the same logical value as self. F and Self must have the same shift and signedness. F must have at least as many bits as Self.

fn add_bits<const N: u32>(self) -> Self::Output<{ _ }, { Self::SHIFT }>

where [(); { _ }]:,

Increase the number of bits used to represent this value. Both the raw and logical values are unchanged. This is a type system operation only. Compilation will fail if the new number of bits is too large for the raw type.

fn set_bits<const N: u32>( self, ) -> Result<Self::Output<N, { Self::SHIFT }>, RangeError>

Set the number of bits used to represent this value. The value is checked at runtime to ensure it is in range for the new number of bits. If succesful, both the raw and logical values are unchanged.

unsafe fn set_bits_unchecked<const N: u32>( self, ) -> Self::Output<N, { Self::SHIFT }>

Set the number of bits used to represent this value. Unsafe: no bounds checking is performed; the caller must ensure that the value fits within the new number of bits. It is almost always better to call .set_bits().unwrap() instead, so that an out-of-bounds value panics with a reasonable message instead of propagating undefined behavior.

fn saturate<const N: u32>(self) -> Self::Output<N, { Self::SHIFT }>

Set the number of bits used to represent this value, saturating in case of overflow.

fn logical_shl<const N: i32>(self) -> Self::Output<{ Self::BITS }, { _ }>

where [(); { _ }]:,

Shift the logical value of this number left by N bits. (N may be negative for a right shift). This is a type system operation only; the raw value is unchanged. The logical value is multiplied by 2^N.

fn logical_shr<const N: i32>(self) -> Self::Output<{ Self::BITS }, { _ }>

where [(); { _ }]:,

Shift the logical value of this number right by N bits. (N may be negative for a left shift). This is a type system operation only; the raw value is unchanged. The logical value is divided by 2^N.

fn raw_shl<const N: u32>(self) -> Self::Output<{ _ }, { _ }>

where [(); { _ }]:,

Shift the raw value of this number left by N bits. Compiles to a left shift. The logical value is unchanged.

fn raw_shr<const N: u32>(self) -> Self::Output<{ _ }, { _ }>

where [(); { _ }]:,

Shift the raw value of this number right by N bits. Compiles to a right shift. The logical value is unchanged, except for truncation of the N least-significant bits.

impl<const BITS: u32, const SHIFT: i32> Ord for I128<BITS, SHIFT>

fn cmp(&self, other: &I128<BITS, SHIFT>) -> Ordering

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const BITS: u32, const SHIFT: i32> PartialEq for I128<BITS, SHIFT>

fn eq(&self, other: &I128<BITS, SHIFT>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<const BITS: u32, const SHIFT: i32> PartialOrd for I128<BITS, SHIFT>

fn partial_cmp(&self, other: &I128<BITS, SHIFT>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<const B0: u32, const B1: u32, const S: i32> Sub<I128<B1, S>> for I128<B0, S>

where [(); { _ }]:,

Two fixed-point integers with the same raw type and the same shift may be subtracted. The result is always signed, even if the inputs were unsigned. The result has the same shift as the inputs, and 1 more bit than the number of bits in the wider of the two inputs.

type Output = I128<{ max(B0, B1) + 1 }, S>

The resulting type after applying the - operator.

fn sub(self: I128<B0, S>, other: I128<B1, S>) -> Self::Output

Performs the - operation.

impl<const BITS: u32, const SHIFT: i32> TryFrom<f32> for I128<BITS, SHIFT>

type Error = RangeError

The type returned in the event of a conversion error.

fn try_from(val: f32) -> Result<Self, Self::Error>

Performs the conversion.

impl<const BITS: u32, const SHIFT: i32> TryFrom<f64> for I128<BITS, SHIFT>

type Error = RangeError

The type returned in the event of a conversion error.

fn try_from(val: f64) -> Result<Self, Self::Error>

Performs the conversion.

impl<const BITS: u32, const SHIFT: i32> Copy for I128<BITS, SHIFT>

impl<const BITS: u32, const SHIFT: i32> Eq for I128<BITS, SHIFT>

impl<const BITS: u32, const SHIFT: i32> StructuralPartialEq for I128<BITS, SHIFT>