Trait polkadot_sdk_frame::arithmetic::per_things::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> { ... }
}

Something that implements a fixed point ration with an arbitrary granularity X, as parts per X.

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

const ACCURACY: Self::Inner

The accuracy of this type.

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.

Object Safety

This trait is not object safe.

Implementors

impl PerThing for PerU16

type Inner = u16

type Upper = u32

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

impl PerThing for Perbill

type Inner = u32

type Upper = u64

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

impl PerThing for Percent

type Inner = u8

type Upper = u16

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

impl PerThing for Permill

type Inner = u32

type Upper = u64

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

impl PerThing for Perquintill

type Inner = u64

type Upper = u128

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