# use comparable_derive::*;
#[derive(Comparable)]
pub struct Synthetics {
    #[comparable_synthetic {
        let full_value = |x: &Self| -> u8 { x.ensemble.iter().sum() };
    }]
    #[comparable_ignore]
    pub ensemble: Vec<u8>,
}

这个结构有一个包含u8值的向量的ensemble字段。然而，在测试中，只要最终的总和保持不变，我们可能不在乎向量内容的更改。这是通过忽略ensemble字段来实现的，这样它就不会生成或描述，同时创建一个从完整对象派生的合成字段，该字段产生总和。

请注意，comparable_synthetic属性的语法相当特定：一系列简单命名的let绑定，其中每个案例的值是一个完整的闭包，它接受包含原始字段的对象的引用（&Self），并为实现了或派生Comparable的某些类型生成一个值。

为结构体派生Comparable：Desc类型

默认情况下，为结构体派生 Comparable 将创建该结构体的“镜像”，包含所有相同的字段，但将每个类型 T 替换为 <T as Comparable>::Desc

# use comparable::*;
struct MyStructDesc {
  bar: <u32 as Comparable>::Desc,
  baz: <u32 as Comparable>::Desc
}

可以使用多个属性宏来影响此过程。

宏属性：self_describing

如果使用 self_describing 属性，则将 Comparable::Desc 类型设置为本身类型，并且 Comparable::describe 方法返回值的克隆。

注意，自描述类型需要以下特质：Clone、Debug 和 PartialEq。

宏属性：no_description

如果您想为类型完全不提供描述，因为您只关心其变化情况，并且永远不会在其他任何上下文中报告值的描述，则可以使用 #[no_description]。这将 Comparable::Desc 类型设置为 unit，并且相应地调整 Comparable::describe 方法。

type Desc = ();

fn describe(&self) -> Self::Desc {
    ()
}

假设在这种情况下，此类值永远不会出现在任何更改输出中，因此如果您看到许多 unit 出现，请考虑不同的方法。

宏属性：describe_type 和 describe_body

通过指定 Comparable::Desc 类型以及 Comparable::describe 函数的主体，您可以更精确地控制描述。基本上，对于以下定义

# use comparable_derive::*;
#[derive(Comparable)]
#[describe_type(T)]
#[describe_body(B)]
struct MyStruct {
  bar: u32,
  baz: u32
}

以下内容将被生成

type Desc = T;

fn describe(&self) -> Self::Desc {
    B
}

这也意味着传递给 describe_body 的表达式参数可以引用 self 参数。以下是一个实际用例

# use comparable_derive::*;
#[cfg_attr(feature = "comparable",
           derive(comparable::Comparable),
           describe_type(String),
           describe_body(self.to_string()))]
struct MyStruct {}

可以使用相同的方法通过其校验和哈希表示大块数据，例如，或者通过其 Merkle 根哈希表示不需要显示的大型数据结构。

宏属性：compare_default

当使用#[compare_default]属性宏时，定义了类型Comparable::Desc，使其与类型Comparable::Change相同，其中Comparable::describe方法通过对比Default::default()的值来实现。

# use comparable::*;
impl comparable::Comparable for MyStruct {
    type Desc = Self::Change;

    fn describe(&self) -> Self::Desc {
        MyStruct::default().comparison(self).unwrap_or_default()
    }

    type Change = Vec<MyStructChange>;

    /* ... */
}

注意，结构体的更改始终是一个向量，因为这允许为每个字段分别报告更改。更多内容将在下一节中介绍。

宏属性：comparable_public和comparable_private

默认情况下，自动生成的类型Comparable::Desc和Comparable::Change的可见性与它们的父类型相同。但是，如果您希望保持原始数据类型私有，但允许导出描述和更改集，则这可能不合适。为了支持这一点——以及相反的情况——您可以使用#[comparable_public]和#[comparable_private]来明确指定这些生成的类型的可见性。

特殊情况：单元结构体

如果一个结构体没有任何字段，它永远不会改变，因此只生成一个单元类型的Comparable::Desc类型。

特殊情况：单例结构体

如果一个结构体只有一个字段（无论是命名的还是未命名的），则使用枚举值向量来记录已更改的内容就不再有意义。在这种情况下，派生过程变得更加简单。

# use comparable_derive::*;
# use comparable::*;
struct MyStruct {
  bar: u32,
}

// The following would be generated by `#[derive(Comparable)]`:

#[derive(PartialEq, Debug)]
struct MyStructDesc {
    bar: <u32 as Comparable>::Desc,
}

#[derive(PartialEq, Debug)]
struct MyStructChange {
    bar: <u32 as Comparable>::Change,
}

impl Comparable for MyStruct {
    type Desc = MyStructDesc;

    fn describe(&self) -> Self::Desc {
        MyStructDesc { bar: self.bar.describe() }
    }

    type Change = MyStructChange;

    fn comparison(&self, other: &Self) -> Changed<Self::Change> {
        self.bar.comparison(&other.bar).map(|x| MyStructChange { bar: x })
    }
}

为结构体派生Comparable：类型Change

对于结构体，默认情况下，派生Comparable将创建一个具有结构体中每个字段变体的枚举，并且它使用这种值的向量来表示更改。这意味着对于以下定义

# use comparable_derive::*;
#[derive(Comparable)]
struct MyStruct {
  bar: u32,
  baz: u32
}

类型Comparable::Change被定义为Vec<MyStructChange>，其中MyStructChange如下所示

#[derive(PartialEq, Debug)]
enum MyStructChange {
    Bar(<u32 as Comparable>::Change),
    Baz(<u32 as Comparable>::Change),
}

impl comparable::Comparable for MyStruct {
    type Desc = MyStructDesc;
    type Change = Vec<MyStructChange>;
}

请注意，如果一个结构体只有一个字段，就没有必要使用向量来指定更改，因为结构体要么没有变化，要么只是那个字段发生了变化。因此，单字段结构体在它们的 Comparable 派生中使用 type Change = [type]Change，而不是像多字段结构体那样使用 type Change = Vec<[type]Change>。

以下是一个简化的例子，展示了如何为具有多个字段的结构体断言更改

assert_changes!(
    &initial_foo, &later_foo,
    Changed::Changed(vec![
        MyStructChange::Bar(...),
        MyStructChange::Baz(...),
    ]));

如果字段没有发生变化，它将不会出现在向量中，并且每个字段最多出现一次。采取这种方法的理由是，如果一个结构体有大量的字段，只要大部分字段保持不变，就可以用一个小的更改集来表示。

枚举

枚举的处理方式与结构体大不相同，因为虽然结构体总是字段的乘积，但枚举不仅可以是变体的和，还可以是乘积的和。

为了更好地解释这一点：这里的“字段的乘积”意味着结构体是一个简单的类型化字段的分组，其中相同的字段对于该结构体的每个值都是可用的。

而枚举是一种变体之间的和，或者选择。然而，其中一些变体可以包含字段的组，就像在变体中嵌入了一个无名的结构体。考虑以下 enum

# use comparable_derive::*;
#[derive(Comparable)]
enum MyEnum {
    One(bool),
    Two { two: Vec<bool>, two_more: u32 },
    Three,
}

在这里，我们看到有一个没有字段的变体（Three），一个有未命名字段的变体（One），以及一个具有像通常结构体一样的命名字段的变体（Two）。然而，问题在于这些嵌入的结构体永远不会被表示为独立的类型，因此我们不能为它们定义 Comparable 并仅计算枚举参数之间的差异。我们也不能简单地创建一个带有真实名称的字段类型的副本并为它生成 Comparable，因为不是每个值都是可复制的或可克隆的，并且自动生成一个具有所有引用类型字段的新层次结构变得非常复杂...

因此，以下被生成，这可能有点冗长，但可以捕捉到任何差异的全貌

enum MyEnumChange {
    BothOne(<bool as comparable::Comparable>::Change),
    BothTwo {
        two: Changed<<Vec<bool> as comparable::Comparable>::Change>,
        two_more: Changed<Baz as comparable::Comparable>::Change
    },
    BothThree,
    Different(
        <MyEnum as comparable::Comparable>::Desc,
        <MyEnum as comparable::Comparable>::Desc
    ),
}

请注意，具有单字段变体的不需要使用 Comparable::Change，因为当变体报告为已更改时，该信息已经得到了反映，例如使用 BothOne。在 BothTwo 的情况下，每个字段类型都被包装在 Changed 中，因为可能有一个或两个字段发生了变化。

以下是一个完整的例子，说明了上述枚举的派生内容

# use comparable_derive::*;
# use comparable::*;
enum MyEnum {
    One(bool),
    Two { two: Vec<bool>, two_more: u32 },
    Three,
}

// The following would be generated by `#[derive(Comparable)]`:

#[derive(PartialEq, Debug)]
enum MyEnumDesc {
    One(<bool as Comparable>::Desc),
    Two { two: <Vec<bool> as Comparable>::Desc,
          two_more: <u32 as Comparable>::Desc },
    Three,
}

#[derive(PartialEq, Debug)]
enum MyEnumChange {
    BothOne(<bool as Comparable>::Change),
    BothTwo { two: Changed<<Vec<bool> as Comparable>::Change>,
              two_more: Changed<<u32 as Comparable>::Change> },
    BothThree,
    Different(MyEnumDesc, MyEnumDesc),
}

impl Comparable for MyEnum {
    type Desc = MyEnumDesc;

    fn describe(&self) -> Self::Desc {
        match self {
            MyEnum::One(x) => MyEnumDesc::One(x.describe()),
            MyEnum::Two { two: x, two_more: y } =>
                MyEnumDesc::Two { two: x.describe(),
                                  two_more: y.describe() },
            MyEnum::Three => MyEnumDesc::Three,
        }
    }

    type Change = MyEnumChange;

    fn comparison(&self, other: &Self) -> Changed<Self::Change> {
        match (self, other) {
            (MyEnum::One(x), MyEnum::One(y)) =>
                x.comparison(&y).map(MyEnumChange::BothOne),
            (MyEnum::Two { two: x0, two_more: x1 },
             MyEnum::Two { two: y0, two_more: y1 }) => {
                let c0 = x0.comparison(&y0);
                let c1 = x1.comparison(&y1);
                if c0.is_unchanged() && c1.is_unchanged() {
                    Changed::Unchanged
                } else {
                    Changed::Changed(MyEnumChange::BothTwo {
                        two: c0, two_more: c1
                    })
                }
            }
            (MyEnum::Three, MyEnum::Three) => Changed::Unchanged,
            (_, _) => Changed::Changed(
                MyEnumChange::Different(self.describe(), other.describe()))
        }
    }
}

为枚举派生 Comparable：Desc 类型

默认情况下，对于枚举类型，使用 Comparable 继承会创建该结构的“镜像”，具有相同的变体和字段，但将每个类型 T 替换为 <T as Comparable>::Desc

# use comparable::*;
enum MyEnumDesc {
  Bar(<u32 as Comparable>::Desc),
  Baz { some_field: <u32 as Comparable>::Desc }
}

可以使用与结构体相同的属性宏来影响此过程，但需要注意的是，枚举变体的字段上目前尚不支持合成属性。在此上下文中使用此属性目前会被静默忽略。

待办事项：jww（2021-11-01）：允许枚举变体中存在合成字段。

为枚举类型继承 Comparable：Change 类型

默认情况下，对于枚举类型，使用 Comparable 继承会创建一个相关的 enum，其中原始枚举中的每个变体在 Change 类型中以 Both<Name> 变体表示，并添加了一个名为 Different 的新变体，该变体接受原始枚举的两个描述。

# use comparable_derive::*;
# use comparable::*;
enum MyEnum {
    One(bool),
    Two { two: Vec<bool>, two_more: u32 },
    Three,
}

// The following would be generated by `#[derive(Comparable)]`:

#[derive(PartialEq, Debug)]
enum MyEnumDesc {
    One(<bool as Comparable>::Desc),
    Two { two: <Vec<bool> as Comparable>::Desc,
          two_more: <u32 as Comparable>::Desc },
    Three,
}

#[derive(PartialEq, Debug)]
enum MyEnumChange {
    BothOne(<bool as Comparable>::Change),
    BothTwo(Vec<MyEnumTwoChange>),
    BothThree,
    Different(MyEnumDesc, MyEnumDesc),
}

#[derive(PartialEq, Debug)]
enum MyEnumTwoChange {
    Two(<Vec<bool> as Comparable>::Change),
    TwoMore(<u32 as Comparable>::Change),
}

impl Comparable for MyEnum {
    type Desc = MyEnumDesc;

    fn describe(&self) -> Self::Desc {
        match self {
            MyEnum::One(x) => MyEnumDesc::One(x.describe()),
            MyEnum::Two { two: x, two_more: y } =>
                MyEnumDesc::Two { two: x.describe(),
                                  two_more: y.describe() },
            MyEnum::Three => MyEnumDesc::Three,
        }
    }

    type Change = MyEnumChange;

    fn comparison(&self, other: &Self) -> Changed<Self::Change> {
        match (self, other) {
            (MyEnum::One(x), MyEnum::One(y)) =>
                x.comparison(&y).map(MyEnumChange::BothOne),
            (MyEnum::Two { two: x0, two_more: x1 },
             MyEnum::Two { two: y0, two_more: y1 }) => {
                let c0 = x0.comparison(&y0);
                let c1 = x1.comparison(&y1);
                let changes: Vec<MyEnumTwoChange> = vec![
                    c0.map(MyEnumTwoChange::Two),
                    c1.map(MyEnumTwoChange::TwoMore),
                ].into_iter().flatten().collect();
                if changes.is_empty() {
                    Changed::Unchanged
                } else {
                    Changed::Changed(MyEnumChange::BothTwo(changes))
                }
            }
            (MyEnum::Three, MyEnum::Three) => Changed::Unchanged,
            (_, _) => Changed::Changed(
                MyEnumChange::Different(self.describe(), other.describe()))
        }
    }
}