Trait fp::Fp

pub trait Fp: Clone + Copy + Eq + Ord + PartialEq + PartialOrd + Sized {
    type Raw: Fp + Shl<u32, Output = Self::Raw> + Shr<u32, Output = Self::Raw>;
    type Output<const B: u32, const S: i32>: Fp<Raw = Self::Raw>;

    const BITS: u32;
    const SHIFT: i32;
    const MIN: Self;
    const MAX: Self;
    const SIGNED: bool;

    // Required methods
    unsafe fn new_unchecked(val: Self::Raw) -> Self;
    fn raw(self) -> Self::Raw;
    unsafe fn from_f32_unchecked(val: f32) -> Self;
    unsafe fn from_f64_unchecked(val: f64) -> Self;
    fn into_f32(self) -> f32;
    fn into_f64(self) -> f64;

    // Provided methods
    fn new(val: Self::Raw) -> Result<Self, RangeError> { ... }
    fn from_f32(val: f32) -> Result<Self, RangeError> { ... }
    fn from_f64(val: f64) -> Result<Self, RangeError> { ... }
    fn from_fp<T: Fp, F: Fp<Raw = T>>(val: F) -> Self
       where Self::Raw: TryFrom<T> { ... }
    fn into_fp<T, F: Fp<Raw = T>>(self) -> F
       where T: TryFrom<Self::Raw> + Fp { ... }
    fn add_bits<const N: u32>(self) -> Self::Output<{ _ }, { Self::SHIFT }>
       where [(); { _ }]: { ... }
    fn set_bits<const N: u32>(
        self
    ) -> Result<Self::Output<N, { Self::SHIFT }>, RangeError> { ... }
    unsafe fn set_bits_unchecked<const N: u32>(
        self
    ) -> Self::Output<N, { Self::SHIFT }> { ... }
    fn saturate<const N: u32>(self) -> Self::Output<N, { Self::SHIFT }> { ... }
    fn logical_shl<const N: i32>(self) -> Self::Output<{ Self::BITS }, { _ }>
       where [(); { _ }]: { ... }
    fn logical_shr<const N: i32>(self) -> Self::Output<{ Self::BITS }, { _ }>
       where [(); { _ }]: { ... }
    fn raw_shl<const N: u32>(self) -> Self::Output<{ _ }, { _ }>
       where [(); { _ }]: { ... }
    fn raw_shr<const N: u32>(self) -> Self::Output<{ _ }, { _ }>
       where [(); { _ }]: { ... }
}

A fixed-point number, stored as type Raw, where only the BITS least-significant bits may be nonzero. The raw value is divided by 2.pow(SHIFT) to obtain the logical value.

Required Associated Types

type Raw: Fp + Shl<u32, Output = Self::Raw> + Shr<u32, Output = Self::Raw>

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>: Fp<Raw = Self::Raw>

The type that this fixed point number will become after BITS and/or SHIFT are changed by an operation. Typically this is one of the Fp* structs, e.g. FpI64.

Required Associated Constants

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

In other words, positive SHIFT means that the logical value consists of BITS - SHIFT integer bits followed by SHIFT fractional bits, and negative shift means that the logical value consists of BITS - SHIFT integer bits (of which the last -SHIFT bits are zero).

const MIN: Self

Minimum possible value of this type.

const MAX: Self

Maximum possible value of this type.

const SIGNED: bool

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

Required Methods

unsafe fn new_unchecked(val: Self::Raw) -> 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) -> Self::Raw

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

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn into_f32(self) -> f32

Return the logical value of Self as f32. Truncation is possible.

fn into_f64(self) -> f64

Return the logical value of Self as f64. Truncation is possible.

Provided Methods

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.

Examples found in repository

examples/main.rs (line 10)

fn main() {
    // There are many ways to create a new fixed-point number
    let options: [FpI32<10, 5>; 4] = [
        FpI32::from_f32(3.125).unwrap(),
        FpI32::from_f64(3.125).unwrap(),
        FpI32::new(100).unwrap(),
        100i32.logical_shr::<5>().set_bits().unwrap(),
    ];
    assert!(options.iter().min() == options.iter().max());  // all equal

    // Arithmetic works pretty much seamlessly
    let a = 12i32.set_bits::<5>().unwrap();
    let b = (-1i32).set_bits::<1>().unwrap();
    let c = a + b;  // type of C is FpI32<6, 0>

    // Addition is associative in value, but not in type
    let d: FpI32<6, 0> = a + (b + b);
    let e: FpI32<7, 0> = (a + b) + b;

    let x = FpI32::<21, 20>::from_f32(0.497).unwrap();
    let y = x.div_const::<12>();
    let z = x + (-y);
    println!("{} {}", x.raw(), x.into_f64());
    println!("{} {}", z.raw(), z.into_f64());
}

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.

Examples found in repository

examples/main.rs (line 8)

fn main() {
    // There are many ways to create a new fixed-point number
    let options: [FpI32<10, 5>; 4] = [
        FpI32::from_f32(3.125).unwrap(),
        FpI32::from_f64(3.125).unwrap(),
        FpI32::new(100).unwrap(),
        100i32.logical_shr::<5>().set_bits().unwrap(),
    ];
    assert!(options.iter().min() == options.iter().max());  // all equal

    // Arithmetic works pretty much seamlessly
    let a = 12i32.set_bits::<5>().unwrap();
    let b = (-1i32).set_bits::<1>().unwrap();
    let c = a + b;  // type of C is FpI32<6, 0>

    // Addition is associative in value, but not in type
    let d: FpI32<6, 0> = a + (b + b);
    let e: FpI32<7, 0> = (a + b) + b;

    let x = FpI32::<21, 20>::from_f32(0.497).unwrap();
    let y = x.div_const::<12>();
    let z = x + (-y);
    println!("{} {}", x.raw(), x.into_f64());
    println!("{} {}", z.raw(), z.into_f64());
}

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.

Examples found in repository

examples/main.rs (line 9)

fn main() {
    // There are many ways to create a new fixed-point number
    let options: [FpI32<10, 5>; 4] = [
        FpI32::from_f32(3.125).unwrap(),
        FpI32::from_f64(3.125).unwrap(),
        FpI32::new(100).unwrap(),
        100i32.logical_shr::<5>().set_bits().unwrap(),
    ];
    assert!(options.iter().min() == options.iter().max());  // all equal

    // Arithmetic works pretty much seamlessly
    let a = 12i32.set_bits::<5>().unwrap();
    let b = (-1i32).set_bits::<1>().unwrap();
    let c = a + b;  // type of C is FpI32<6, 0>

    // Addition is associative in value, but not in type
    let d: FpI32<6, 0> = a + (b + b);
    let e: FpI32<7, 0> = (a + b) + b;

    let x = FpI32::<21, 20>::from_f32(0.497).unwrap();
    let y = x.div_const::<12>();
    let z = x + (-y);
    println!("{} {}", x.raw(), x.into_f64());
    println!("{} {}", z.raw(), z.into_f64());
}

fn from_fp<T: Fp, F: Fp<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: Fp<Raw = T>>(self) -> F

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

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.

Examples found in repository

examples/main.rs (line 11)

fn main() {
    // There are many ways to create a new fixed-point number
    let options: [FpI32<10, 5>; 4] = [
        FpI32::from_f32(3.125).unwrap(),
        FpI32::from_f64(3.125).unwrap(),
        FpI32::new(100).unwrap(),
        100i32.logical_shr::<5>().set_bits().unwrap(),
    ];
    assert!(options.iter().min() == options.iter().max());  // all equal

    // Arithmetic works pretty much seamlessly
    let a = 12i32.set_bits::<5>().unwrap();
    let b = (-1i32).set_bits::<1>().unwrap();
    let c = a + b;  // type of C is FpI32<6, 0>

    // Addition is associative in value, but not in type
    let d: FpI32<6, 0> = a + (b + b);
    let e: FpI32<7, 0> = (a + b) + b;

    let x = FpI32::<21, 20>::from_f32(0.497).unwrap();
    let y = x.div_const::<12>();
    let z = x + (-y);
    println!("{} {}", x.raw(), x.into_f64());
    println!("{} {}", z.raw(), z.into_f64());
}

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.

Examples found in repository

examples/main.rs (line 11)

fn main() {
    // There are many ways to create a new fixed-point number
    let options: [FpI32<10, 5>; 4] = [
        FpI32::from_f32(3.125).unwrap(),
        FpI32::from_f64(3.125).unwrap(),
        FpI32::new(100).unwrap(),
        100i32.logical_shr::<5>().set_bits().unwrap(),
    ];
    assert!(options.iter().min() == options.iter().max());  // all equal

    // Arithmetic works pretty much seamlessly
    let a = 12i32.set_bits::<5>().unwrap();
    let b = (-1i32).set_bits::<1>().unwrap();
    let c = a + b;  // type of C is FpI32<6, 0>

    // Addition is associative in value, but not in type
    let d: FpI32<6, 0> = a + (b + b);
    let e: FpI32<7, 0> = (a + b) + b;

    let x = FpI32::<21, 20>::from_f32(0.497).unwrap();
    let y = x.div_const::<12>();
    let z = x + (-y);
    println!("{} {}", x.raw(), x.into_f64());
    println!("{} {}", z.raw(), z.into_f64());
}

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.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl Fp for i8

type Raw = i8

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

const BITS: u32 = 8u32

const SHIFT: i32 = 0i32

const MIN: i8 = -128i8

const MAX: i8 = 127i8

const SIGNED: bool = true

unsafe fn new_unchecked(val: i8) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> i8

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for i16

type Raw = i16

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

const BITS: u32 = 16u32

const SHIFT: i32 = 0i32

const MIN: i16 = -32_768i16

const MAX: i16 = 32_767i16

const SIGNED: bool = true

unsafe fn new_unchecked(val: i16) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> i16

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for i32

type Raw = i32

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

const BITS: u32 = 32u32

const SHIFT: i32 = 0i32

const MIN: i32 = -2_147_483_648i32

const MAX: i32 = 2_147_483_647i32

const SIGNED: bool = true

unsafe fn new_unchecked(val: i32) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> i32

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for i64

type Raw = i64

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

const BITS: u32 = 64u32

const SHIFT: i32 = 0i32

const MIN: i64 = -9_223_372_036_854_775_808i64

const MAX: i64 = 9_223_372_036_854_775_807i64

const SIGNED: bool = true

unsafe fn new_unchecked(val: i64) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> i64

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for i128

type Raw = i128

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

const BITS: u32 = 128u32

const SHIFT: i32 = 0i32

const MIN: i128 = -170_141_183_460_469_231_731_687_303_715_884_105_728i128

const MAX: i128 = 170_141_183_460_469_231_731_687_303_715_884_105_727i128

const SIGNED: bool = true

unsafe fn new_unchecked(val: i128) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> i128

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for isize

type Raw = isize

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

const BITS: u32 = 32u32

const SHIFT: i32 = 0i32

const MIN: isize = -2_147_483_648isize

const MAX: isize = 2_147_483_647isize

const SIGNED: bool = true

unsafe fn new_unchecked(val: isize) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> isize

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for u8

type Raw = u8

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

const BITS: u32 = 8u32

const SHIFT: i32 = 0i32

const MIN: u8 = 0u8

const MAX: u8 = 255u8

const SIGNED: bool = false

unsafe fn new_unchecked(val: u8) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> u8

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for u16

type Raw = u16

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

const BITS: u32 = 16u32

const SHIFT: i32 = 0i32

const MIN: u16 = 0u16

const MAX: u16 = 65_535u16

const SIGNED: bool = false

unsafe fn new_unchecked(val: u16) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> u16

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for u32

type Raw = u32

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

const BITS: u32 = 32u32

const SHIFT: i32 = 0i32

const MIN: u32 = 0u32

const MAX: u32 = 4_294_967_295u32

const SIGNED: bool = false

unsafe fn new_unchecked(val: u32) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> u32

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for u64

type Raw = u64

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

const BITS: u32 = 64u32

const SHIFT: i32 = 0i32

const MIN: u64 = 0u64

const MAX: u64 = 18_446_744_073_709_551_615u64

const SIGNED: bool = false

unsafe fn new_unchecked(val: u64) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> u64

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for u128

type Raw = u128

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

const BITS: u32 = 128u32

const SHIFT: i32 = 0i32

const MIN: u128 = 0u128

const MAX: u128 = 340_282_366_920_938_463_463_374_607_431_768_211_455u128

const SIGNED: bool = false

unsafe fn new_unchecked(val: u128) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> u128

fn into_f32(self) -> f32

fn into_f64(self) -> f64

impl Fp for usize

type Raw = usize

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

const BITS: u32 = 32u32

const SHIFT: i32 = 0i32

const MIN: usize = 0usize

const MAX: usize = 4_294_967_295usize

const SIGNED: bool = false

unsafe fn new_unchecked(val: usize) -> Self

unsafe fn from_f32_unchecked(val: f32) -> Self

unsafe fn from_f64_unchecked(val: f64) -> Self

fn raw(self) -> usize

fn into_f32(self) -> f32

fn into_f64(self) -> f64

Implementors

impl<const BITS: u32, const SHIFT: i32> Fp for FpI8<BITS, SHIFT>

type Raw = i8

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpI16<BITS, SHIFT>

type Raw = i16

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpI32<BITS, SHIFT>

type Raw = i32

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpI64<BITS, SHIFT>

type Raw = i64

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpI128<BITS, SHIFT>

type Raw = i128

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpIsize<BITS, SHIFT>

type Raw = isize

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = true

impl<const BITS: u32, const SHIFT: i32> Fp for FpU8<BITS, SHIFT>

type Raw = u8

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false

impl<const BITS: u32, const SHIFT: i32> Fp for FpU16<BITS, SHIFT>

type Raw = u16

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false

impl<const BITS: u32, const SHIFT: i32> Fp for FpU32<BITS, SHIFT>

type Raw = u32

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false

impl<const BITS: u32, const SHIFT: i32> Fp for FpU64<BITS, SHIFT>

type Raw = u64

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false

impl<const BITS: u32, const SHIFT: i32> Fp for FpU128<BITS, SHIFT>

type Raw = u128

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false

impl<const BITS: u32, const SHIFT: i32> Fp for FpUsize<BITS, SHIFT>

type Raw = usize

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

const BITS: u32 = _

const SHIFT: i32 = SHIFT

const MIN: Self = _

const MAX: Self = _

const SIGNED: bool = false