# 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 字段。然而，在测试中，我们可能不在乎向量内容的更改，只要最终的总和保持相同即可。这是通过忽略该字段，使其根本不会生成或描述，同时创建一个从完整对象派生的合成字段来实现的，该字段产生总和。

请注意，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 类型设置为单元类型，并且相应地实现 Comparable::describe 方法

type Desc = ();

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

假设在这种情况下，这些值永远不会出现在任何更改输出中，因此如果看到大量单元出现，请考虑不同的方法。

宏属性：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(...),
    ]));

如果一个字段没有被更改，它不会出现在向量中，每个字段最多出现一次。采取这种方法的理由是，具有许多字段的许多结构体可以通过一个小的更改集来表示，如果大多数其他字段保持不变。

枚举

枚举的处理方式与结构体截然不同，原因在于结构体总是字段的组合产物，而枚举可以不仅仅是变体的总和——它还可以是多个组合产物的总和。

为了更好地理解这一点：“字段的组合产物”意味着结构体是一个简单地将类型化的字段分组，其中相同的字段适用于这种结构体的每一个值。

与此同时，枚举是一种变体的总和或选择。然而，其中一些变体可以包含字段的组合，就像变体中嵌入了一个无名的结构体。考虑以下枚举：

# 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 会创建一个相关的枚举，其中原始枚举的每个变体在 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()))
        }
    }
}