反序列化

带名称的结构体可以像这样无问题地进行反序列化

#[decimal(6)]
#[zero_copy]
#[derive(AnchorSerialize, AnchorDeserialize, ...)]
pub struct Price {
    pub v: u128,
}

基本操作

宏生成的所有方法都使用检查数学并在溢出时恐慌。尽可能地对运算符进行重载，以方便使用。

使用上面定义的类型的基本示例看起来像这样

let price = Price::from_integer(10); // this corresponds with 10 * 10^k so 10^7 in this case

let discount = Percentage::new(10); // using new doesn't account for decimal places so 0.10 here

// addition expects being called for left and right values being of the same type
// multiplication doesn't so you can be used like this:
let price = price * (Percentage::from_integer(1) - discount); // the resulting type is always the type of the left value

更多示例请参阅walkthrough.rs

宏的参数

如前所述，宏的第一个参数控制小数点后的位数。它的范围在0到38之间。它可以由Price::scale()读取。第二个参数是可选的，可能更难理解

大类型

第二个参数有一个奇怪的名称，叫做大类型。它设置在调用带有big名称的方法时使用的类型。它的目的是避免临时溢出，即使该值适合给定的类型，但在计算返回值时也会发生溢出。考虑下面的例子

#[decimal(2)]
#[derive(Default, Debug, Clone, Copy, PartialEq)]
struct Percentage(u8, u128);

let p = Percentage(110); // 110% or 1.1

// assert_eq!(p * p, Percentage(121));      <- this would panic
assert_eq!(p.big_mul(p), Percentage(121));  <- this will work fine

要了解为什么它会这样工作，请看decimal在底层是如何进行乘法的

内部发生了什么（在数学方面）

这个库的大部分使用的是非常基本的数学，下面列出了一些可能不明显的事情

保持比例

使用值进行两个百分比的乘法（比例为2）看起来像这样

(x/ 10^2) / (y/ 10^2) =x/y

（上帝，我恨gh不允许使用LaTeX）

使用数字会这样

10% / 10% = 10 / 10 = 1

这显然是错误的。我们需要做的是将每个值乘以10^scale。所以它应该这样看起来

(x/ 10^比例) / (y/ 10^比例)×10^比例=x/y ×10^比例

这与上面的例子相符

总的来说，在每次乘法操作之后都需要进行除法，反之亦然。这是这个库的第一个目的——抽象它，以减少代码、错误和浪费时间。

这里重要的是，乘法必须在除法之前进行，以保持精度，但这也被抽象化了。

舍入误差

默认情况下，每个方法都向下舍入，但有一个以up结尾的方法进行相反方向的舍入。

舍入通过将denominator - 1添加到分子来实现，所以mul_up看起来像这样

(x × y+ 10^比例- 1) / 10^比例

例如，对于10% × 1%

(10×1 + (10^2 - 1)) / (10^2) = 109 / 100 = 1%

内部发生了什么（在代码层面上）

正如你所知，整个库都是宏的形式。在宏内部，它以通用形式实现了一些特质的实现，以便可以在任何两个实现之间调用方法。

• Decimal - 所有其他特性都依赖于它，通过实现它，您可以与其他任何特性一起使用您的实现。一个用例可能是将其实现为2进制

  • type U: Debug + Default; - 一个关联类型，存储值的原始类型（或非原始类型），在宏被调用的结构体中的第一个字段的类型
  • fn get(&self) -> Self::U; - 十进制数的值
  • fn new(value: Self::U) -> Self; - 构造函数
  • fn here<Y: TryFrom<Self::U>>(&self) -> Y; - 与get相同，但还会尝试转换为所需值
  • fn scale() -> u8; - 十进制位数的数量（在宏中给出）
  • fn one<T: TryFrom<u128>>() -> T; - 基本上是10^scale，在编译时评估
  • fn almost_one<T: TryFrom<u128>>() -> T; - 与上面相同，但 -1，也适用于编译时

• std::ops - 加法、减法、乘法和除法，以及相应的赋值运算符（+=）

• pub trait BigOps<T> - 与上面相同，但使用先前提到的大的数据类型进行计算

• pub trait Others<T> - 用于未来操作的特质，目前只有两个方法

  • fn mul_up(self, rhs: T) -> Self; - 乘法，向上取整
  • fn div_up(self, rhs: T) -> Self; - 除法，向上取整

• pub trait Factories<T> - 作为构造函数使用的方法（不包括 new）

  • fn from_integer(integer: T) -> Self; - 使用值 integer × 10^scale 创建 self
  • fn from_scale(integer: T, scale: u8) -> Self; - 使用值 integer × 10^(scale - given\_scale) 创建 self
  • fn from_scale_up(integer: T, scale: u8) -> Self; - 与上述相同，但向上取整

• pub trait BetweenDecimals<T> - 用于不同类型之间的转换，可能具有不同的缩放比例

• pub trait ToValue<T, B> 和 pub trait ByNumber<B> - 可以一起使用，将溢出的值移出类型范围，然后再放回类型中，通常不需要经常使用