Trait PerThing

pub trait PerThing:
    Sized
    + Saturating
    + Copy
    + Default
    + Eq
    + PartialEq
    + Ord
    + PartialOrd
    + Bounded
    + Debug
    + Div<Output = Self>
    + Mul<Output = Self>
    + Pow<usize, Output = Self> {
    type Inner: BaseArithmetic + Unsigned + Copy + Into<u128> + Debug + MultiplyRational;
    type Upper: BaseArithmetic + Copy + From<Self::Inner> + TryInto<Self::Inner> + UniqueSaturatedInto<Self::Inner> + Unsigned + Debug + MultiplyRational;

    const ACCURACY: Self::Inner;

    // Required methods
    fn deconstruct(self) -> Self::Inner;
    fn from_parts(parts: Self::Inner) -> Self;
    fn from_float(x: f64) -> Self;
    fn from_rational_with_rounding<N>(
        p: N,
        q: N,
        rounding: Rounding,
    ) -> Result<Self, ()>
       where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>,
             Self::Inner: Into<N>;

    // Provided methods
    fn zero() -> Self { ... }
    fn is_zero(&self) -> bool { ... }
    fn one() -> Self { ... }
    fn is_one(&self) -> bool { ... }
    fn less_epsilon(self) -> Self { ... }
    fn try_less_epsilon(self) -> Result<Self, Self> { ... }
    fn plus_epsilon(self) -> Self { ... }
    fn try_plus_epsilon(self) -> Result<Self, Self> { ... }
    fn from_percent(x: Self::Inner) -> Self { ... }
    fn square(self) -> Self { ... }
    fn left_from_one(self) -> Self { ... }
    fn mul_floor<N>(self, b: N) -> N
       where N: MultiplyArg + UniqueSaturatedInto<Self::Inner>,
             Self::Inner: Into<N> { ... }
    fn mul_ceil<N>(self, b: N) -> N
       where N: MultiplyArg + UniqueSaturatedInto<Self::Inner>,
             Self::Inner: Into<N> { ... }
    fn saturating_reciprocal_mul<N>(self, b: N) -> N
       where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>,
             Self::Inner: Into<N> { ... }
    fn saturating_reciprocal_mul_floor<N>(self, b: N) -> N
       where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>,
             Self::Inner: Into<N> { ... }
    fn saturating_reciprocal_mul_ceil<N>(self, b: N) -> N
       where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>,
             Self::Inner: Into<N> { ... }
    fn from_fraction(x: f64) -> Self { ... }
    fn from_rational<N>(p: N, q: N) -> Self
       where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>,
             Self::Inner: Into<N> { ... }
    fn from_rational_approximation<N>(p: N, q: N) -> Self
       where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>,
             Self::Inner: Into<N> { ... }
}

Re-export top-level arithmetic stuff. Something that implements a fixed point ration with an arbitrary granularity X, as parts per X.

Required Associated Constants

const ACCURACY: Self::Inner

The accuracy of this type.

Required Associated Types

type Inner: BaseArithmetic + Unsigned + Copy + Into<u128> + Debug + MultiplyRational

The data type used to build this per-thingy.

type Upper: BaseArithmetic + Copy + From<Self::Inner> + TryInto<Self::Inner> + UniqueSaturatedInto<Self::Inner> + Unsigned + Debug + MultiplyRational

A data type larger than Self::Inner, used to avoid overflow in some computations. It must be able to compute ACCURACY^2.

Required Methods

fn deconstruct(self) -> Self::Inner

Consume self and return the number of parts per thing.

fn from_parts(parts: Self::Inner) -> Self

Build this type from a number of parts per thing.

fn from_float(x: f64) -> Self

Converts a fraction into Self.

fn from_rational_with_rounding<N>( p: N, q: N, rounding: Rounding, ) -> Result<Self, ()>

where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>, Self::Inner: Into<N>,

Approximate the fraction p/q into a per-thing fraction.

The computation of this approximation is performed in the generic type N. Given M as the data type that can hold the maximum value of this per-thing (e.g. u32 for Perbill), this can only work if N == M or N: From<M> + TryInto<M>.

In the case of an overflow (or divide by zero), an Err is returned.

Rounding is determined by the parameter rounding, i.e.

// 989/100 is technically closer to 99%.
assert_eq!(
	Percent::from_rational_with_rounding(989u64, 1000, Down).unwrap(),
	Percent::from_parts(98),
);
assert_eq!(
	Percent::from_rational_with_rounding(984u64, 1000, NearestPrefUp).unwrap(),
	Percent::from_parts(98),
);
assert_eq!(
	Percent::from_rational_with_rounding(985u64, 1000, NearestPrefDown).unwrap(),
	Percent::from_parts(98),
);
assert_eq!(
	Percent::from_rational_with_rounding(985u64, 1000, NearestPrefUp).unwrap(),
	Percent::from_parts(99),
);
assert_eq!(
	Percent::from_rational_with_rounding(986u64, 1000, NearestPrefDown).unwrap(),
	Percent::from_parts(99),
);
assert_eq!(
	Percent::from_rational_with_rounding(981u64, 1000, Up).unwrap(),
	Percent::from_parts(99),
);
assert_eq!(
	Percent::from_rational_with_rounding(1001u64, 1000, Up),
	Err(()),
);

assert_eq!(
	Percent::from_rational_with_rounding(981u64, 1000, Up).unwrap(),
	Percent::from_parts(99),
);

Provided Methods

fn zero() -> Self

Equivalent to Self::from_parts(0).

fn is_zero(&self) -> bool

Return true if this is nothing.

fn one() -> Self

Equivalent to Self::from_parts(Self::ACCURACY).

fn is_one(&self) -> bool

Return true if this is one.

fn less_epsilon(self) -> Self

Return the next lower value to self or self if it is already zero.

fn try_less_epsilon(self) -> Result<Self, Self>

Return the next lower value to self or an error with the same value if self is already zero.

fn plus_epsilon(self) -> Self

Return the next higher value to self or self if it is already one.

fn try_plus_epsilon(self) -> Result<Self, Self>

Return the next higher value to self or an error with the same value if self is already one.

fn from_percent(x: Self::Inner) -> Self

Build this type from a percent. Equivalent to Self::from_parts(x * Self::ACCURACY / 100) but more accurate and can cope with potential type overflows.

fn square(self) -> Self

Return the product of multiplication of this value by itself.

fn left_from_one(self) -> Self

Return the part left when self is saturating-subtracted from Self::one().

fn mul_floor<N>(self, b: N) -> N

where N: MultiplyArg + UniqueSaturatedInto<Self::Inner>, Self::Inner: Into<N>,

Multiplication that always rounds down to a whole number. The standard Mul rounds to the nearest whole number.

// round to nearest
assert_eq!(Percent::from_percent(34) * 10u64, 3);
assert_eq!(Percent::from_percent(36) * 10u64, 4);

// round down
assert_eq!(Percent::from_percent(34).mul_floor(10u64), 3);
assert_eq!(Percent::from_percent(36).mul_floor(10u64), 3);

fn mul_ceil<N>(self, b: N) -> N

where N: MultiplyArg + UniqueSaturatedInto<Self::Inner>, Self::Inner: Into<N>,

Multiplication that always rounds the result up to a whole number. The standard Mul rounds to the nearest whole number.

// round to nearest
assert_eq!(Percent::from_percent(34) * 10u64, 3);
assert_eq!(Percent::from_percent(36) * 10u64, 4);

// round up
assert_eq!(Percent::from_percent(34).mul_ceil(10u64), 4);
assert_eq!(Percent::from_percent(36).mul_ceil(10u64), 4);

fn saturating_reciprocal_mul<N>(self, b: N) -> N

where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>, Self::Inner: Into<N>,

Saturating multiplication by the reciprocal of self. The result is rounded to the nearest whole number and saturates at the numeric bounds instead of overflowing.

assert_eq!(Percent::from_percent(50).saturating_reciprocal_mul(10u64), 20);

fn saturating_reciprocal_mul_floor<N>(self, b: N) -> N

where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>, Self::Inner: Into<N>,

Saturating multiplication by the reciprocal of self. The result is rounded down to the nearest whole number and saturates at the numeric bounds instead of overflowing.

// round to nearest
assert_eq!(Percent::from_percent(60).saturating_reciprocal_mul(10u64), 17);
// round down
assert_eq!(Percent::from_percent(60).saturating_reciprocal_mul_floor(10u64), 16);

fn saturating_reciprocal_mul_ceil<N>(self, b: N) -> N

where N: ReciprocalArg + UniqueSaturatedInto<Self::Inner>, Self::Inner: Into<N>,

Saturating multiplication by the reciprocal of self. The result is rounded up to the nearest whole number and saturates at the numeric bounds instead of overflowing.

// round to nearest
assert_eq!(Percent::from_percent(61).saturating_reciprocal_mul(10u64), 16);
// round up
assert_eq!(Percent::from_percent(61).saturating_reciprocal_mul_ceil(10u64), 17);

fn from_fraction(x: f64) -> Self

👎Deprecated: Use from_float instead

Same as Self::from_float.

fn from_rational<N>(p: N, q: N) -> Self

where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>, Self::Inner: Into<N>,

Approximate the fraction p/q into a per-thing fraction. This will never overflow.

The computation of this approximation is performed in the generic type N. Given M as the data type that can hold the maximum value of this per-thing (e.g. u32 for perbill), this can only work if N == M or N: From<M> + TryInto<M>.

Note that this always rounds down, i.e.

// 989/1000 is technically closer to 99%.
assert_eq!(
	Percent::from_rational(989u64, 1000),
	Percent::from_parts(98),
);

fn from_rational_approximation<N>(p: N, q: N) -> Self

where N: RationalArg + TryInto<Self::Inner> + TryInto<Self::Upper>, Self::Inner: Into<N>,

👎Deprecated: Use from_rational instead

Same as Self::from_rational.

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.

Implementors

impl PerThing for PerU16

const ACCURACY: <PerU16 as PerThing>::Inner = {transmute(0xffff): <sp_arithmetic::PerU16 as sp_arithmetic::PerThing>::Inner}

type Inner = u16

type Upper = u32

impl PerThing for Perbill

const ACCURACY: <Perbill as PerThing>::Inner = {transmute(0x3b9aca00): <sp_arithmetic::Perbill as sp_arithmetic::PerThing>::Inner}

type Inner = u32

type Upper = u64

impl PerThing for Percent

const ACCURACY: <Percent as PerThing>::Inner = {transmute(0x64): <sp_arithmetic::Percent as sp_arithmetic::PerThing>::Inner}

type Inner = u8

type Upper = u16

impl PerThing for Permill

const ACCURACY: <Permill as PerThing>::Inner = {transmute(0x000f4240): <sp_arithmetic::Permill as sp_arithmetic::PerThing>::Inner}

type Inner = u32

type Upper = u64

impl PerThing for Perquintill

const ACCURACY: <Perquintill as PerThing>::Inner = {transmute(0x0de0b6b3a7640000): <sp_arithmetic::Perquintill as sp_arithmetic::PerThing>::Inner}

type Inner = u64

type Upper = u128