Trait Num

Source

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

    const BITS: u32;
    const SHIFT: i32;
    const MIN: Self;
    const MAX: Self;
    const SIGNED: bool;
Show 19 methods
    // 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: Num, F: Num<Raw = T>>(val: F) -> Self
       where Self::Raw: TryFrom<T> { ... }
    fn into_fp<T, F: Num<Raw = T>>(self) -> F
       where T: TryFrom<Self::Raw> + Num { ... }
    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 [(); { _ }]: { ... }
}

Expand description

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 Constants§

Source

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

Source

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

Source

const MIN: Self

Minimum possible value of this type.

Source

const MAX: Self

Maximum possible value of this type.

Source

const SIGNED: bool

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

Required Associated Types§

Source

type Raw: Num<Raw = Self::Raw> + 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.

Source

type Output<const B: u32, const S: i32>: Num<Raw = Self::Raw>

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

Required Methods§

Source

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.

Source

fn raw(self) -> Self::Raw

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

Source

unsafe fn from_f32_unchecked(val: f32) -> Self

Source

unsafe fn from_f64_unchecked(val: f64) -> Self

Source

fn into_f32(self) -> f32

Return the logical value of Self as f32. Return value is guaranteed to be exact.

Source

fn into_f64(self) -> f64

Return the logical value of Self as f64. Return value is guaranteed to be exact.

Provided Methods§

Source

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

6fn main() {
7    // There are many ways to create a new fixed-point number
8    let options: [fp::I32<10, 5>; 4] = [
9        fp::I32::from_f32(3.125).unwrap(),
10        fp::I32::from_f64(3.125).unwrap(),
11        fp::I32::new(100).unwrap(),
12        100i32.logical_shr::<5>().set_bits().unwrap(),
13    ];
14    assert!(options.iter().min() == options.iter().max()); // all equal
15
16    // Arithmetic works pretty much seamlessly
17    let a = 12i32.set_bits::<5>().unwrap();
18    let b = (-1i32).set_bits::<1>().unwrap();
19    let _ = a + b; // type is I32<6, 0>
20
21    // Addition is associative in value, but not in type
22    let _: fp::I32<6, 0> = a + (b + b);
23    let _: fp::I32<7, 0> = (a + b) + b;
24
25    let x = fp::I32::<21, 20>::from_f32(0.497).unwrap();
26    let y = x / fp::I32::<32, 0>::new(12).unwrap();
27    let z = x + (-y);
28    println!("{} {}", x.raw(), x.into_f64());
29    println!("{} {}", z.raw(), z.into_f64());
30}

Source

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

6fn main() {
7    // There are many ways to create a new fixed-point number
8    let options: [fp::I32<10, 5>; 4] = [
9        fp::I32::from_f32(3.125).unwrap(),
10        fp::I32::from_f64(3.125).unwrap(),
11        fp::I32::new(100).unwrap(),
12        100i32.logical_shr::<5>().set_bits().unwrap(),
13    ];
14    assert!(options.iter().min() == options.iter().max()); // all equal
15
16    // Arithmetic works pretty much seamlessly
17    let a = 12i32.set_bits::<5>().unwrap();
18    let b = (-1i32).set_bits::<1>().unwrap();
19    let _ = a + b; // type is I32<6, 0>
20
21    // Addition is associative in value, but not in type
22    let _: fp::I32<6, 0> = a + (b + b);
23    let _: fp::I32<7, 0> = (a + b) + b;
24
25    let x = fp::I32::<21, 20>::from_f32(0.497).unwrap();
26    let y = x / fp::I32::<32, 0>::new(12).unwrap();
27    let z = x + (-y);
28    println!("{} {}", x.raw(), x.into_f64());
29    println!("{} {}", z.raw(), z.into_f64());
30}

Source

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

6fn main() {
7    // There are many ways to create a new fixed-point number
8    let options: [fp::I32<10, 5>; 4] = [
9        fp::I32::from_f32(3.125).unwrap(),
10        fp::I32::from_f64(3.125).unwrap(),
11        fp::I32::new(100).unwrap(),
12        100i32.logical_shr::<5>().set_bits().unwrap(),
13    ];
14    assert!(options.iter().min() == options.iter().max()); // all equal
15
16    // Arithmetic works pretty much seamlessly
17    let a = 12i32.set_bits::<5>().unwrap();
18    let b = (-1i32).set_bits::<1>().unwrap();
19    let _ = a + b; // type is I32<6, 0>
20
21    // Addition is associative in value, but not in type
22    let _: fp::I32<6, 0> = a + (b + b);
23    let _: fp::I32<7, 0> = (a + b) + b;
24
25    let x = fp::I32::<21, 20>::from_f32(0.497).unwrap();
26    let y = x / fp::I32::<32, 0>::new(12).unwrap();
27    let z = x + (-y);
28    println!("{} {}", x.raw(), x.into_f64());
29    println!("{} {}", z.raw(), z.into_f64());
30}

Source

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.

Source

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.

Source

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.

Source

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

6fn main() {
7    // There are many ways to create a new fixed-point number
8    let options: [fp::I32<10, 5>; 4] = [
9        fp::I32::from_f32(3.125).unwrap(),
10        fp::I32::from_f64(3.125).unwrap(),
11        fp::I32::new(100).unwrap(),
12        100i32.logical_shr::<5>().set_bits().unwrap(),
13    ];
14    assert!(options.iter().min() == options.iter().max()); // all equal
15
16    // Arithmetic works pretty much seamlessly
17    let a = 12i32.set_bits::<5>().unwrap();
18    let b = (-1i32).set_bits::<1>().unwrap();
19    let _ = a + b; // type is I32<6, 0>
20
21    // Addition is associative in value, but not in type
22    let _: fp::I32<6, 0> = a + (b + b);
23    let _: fp::I32<7, 0> = (a + b) + b;
24
25    let x = fp::I32::<21, 20>::from_f32(0.497).unwrap();
26    let y = x / fp::I32::<32, 0>::new(12).unwrap();
27    let z = x + (-y);
28    println!("{} {}", x.raw(), x.into_f64());
29    println!("{} {}", z.raw(), z.into_f64());
30}

Source

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.

Source

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.

Source

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.

Source

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

6fn main() {
7    // There are many ways to create a new fixed-point number
8    let options: [fp::I32<10, 5>; 4] = [
9        fp::I32::from_f32(3.125).unwrap(),
10        fp::I32::from_f64(3.125).unwrap(),
11        fp::I32::new(100).unwrap(),
12        100i32.logical_shr::<5>().set_bits().unwrap(),
13    ];
14    assert!(options.iter().min() == options.iter().max()); // all equal
15
16    // Arithmetic works pretty much seamlessly
17    let a = 12i32.set_bits::<5>().unwrap();
18    let b = (-1i32).set_bits::<1>().unwrap();
19    let _ = a + b; // type is I32<6, 0>
20
21    // Addition is associative in value, but not in type
22    let _: fp::I32<6, 0> = a + (b + b);
23    let _: fp::I32<7, 0> = (a + b) + b;
24
25    let x = fp::I32::<21, 20>::from_f32(0.497).unwrap();
26    let y = x / fp::I32::<32, 0>::new(12).unwrap();
27    let z = x + (-y);
28    println!("{} {}", x.raw(), x.into_f64());
29    println!("{} {}", z.raw(), z.into_f64());
30}

Source

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.

Source

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.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait NumCopy item path

Required Associated Constants§

const BITS: u32

const SHIFT: i32

const MIN: Self

const MAX: Self

const SIGNED: bool

Required Associated Types§

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

type Output<const B: u32, const S: i32>: Num<Raw = Self::Raw>

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: Num, F: Num<Raw = T>>(val: F) -> Selfwhere Self::Raw: TryFrom<T>,

fn into_fp<T, F: Num<Raw = T>>(self) -> Fwhere T: TryFrom<Self::Raw> + Num,

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 [(); { _ }]:,

Dyn Compatibility§

Implementations on Foreign Types§

impl Num for i8

fn into_f32(self) -> f32

fn into_f64(self) -> f64

const BITS: u32 = 8u32

const SHIFT: i32 = 0i32

const MIN: i8 = -128i8

const MAX: i8 = 127i8

const SIGNED: bool = true

type Raw = i8

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

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

impl Num for i16

fn into_f32(self) -> f32

fn into_f64(self) -> f64

const BITS: u32 = 16u32

const SHIFT: i32 = 0i32

const MIN: i16 = -32_768i16

const MAX: i16 = 32_767i16

const SIGNED: bool = true

type Raw = i16

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

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

impl Num for i32

fn into_f32(self) -> f32

fn into_f64(self) -> f64

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

type Raw = i32

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

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

impl Num for i64

fn into_f32(self) -> f32

fn into_f64(self) -> f64

const BITS: u32 = 64u32

const SHIFT: i32 = 0i32

Trait Num

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

fn into_fp<T, F: Num<Raw = T>>(self) -> F
where T: TryFrom<Self::Raw> + Num,

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

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 [(); { _ }]:,