Rust 编程语言内置的 derive 属性可以快速地替我们的类型加上内置的特性,不过会要求该类型内的字段也都要先实作相同的特性,而且很多时候利用 derive 属性实作出来的特性并不能达到我们期望的功能。

好比说以下这个用来作为唯读数据库的数据模型的结构体:

#[derive(PartialEq, Eq, Hash)]
pub struct Person {
    uid: u64,
    name: String,
    age: u8
}

我们希望这个 Person 结构体可以被哈希,且拥有判断两个 Person 结构体是否相同的功能。以上的实作方式虽然在使用起来并没有什么太大的问题,但是性能不会很好,因为透过 derive 属性实作的 Hash 特性,会去计算所有字段的哈希值,然而在这里我们其实只要去计算 uid 这个字段的哈希值就可以了。同理,PartialEq 特性也是一样只需要去判断 uid 这个字段是否 PartialEq 就好了,实在不需要用上所有字段。

再来,如果我们加了某个没有同时实作 Hash、PartialEq 和 Eq 特性的字段,这个 Person 结构体就没有办法被编译了。

例如:

#[derive(PartialEq, Eq, Hash)]
pub struct Person {
    uid: u64,
    name: String,
    age: u8,
    score: f64,
}

以上程序,由于类型为 f64 的 score 字段没有实作 Eq 特性,更不用说有去实作 Hash 特性了,所以会编译失败。

还有,除了无法灵活调整特性实作外,derive 属性能实作的特性种类也有限。像是 From 和 Into 特性就无法实作。

derive 属性也可能会替泛型参数加上过多的约束,例如:

struct NewType<T>(T);

impl<T> Hash for NewType<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        0u8.hash(state)
    }
}

#[derive(Hash)]
struct B<T> {
    f1: NewType<T>,
}

以上程序,B<T> 会在 T: Hash 的约束下被实作 Hash 特性。然而实作给 NewType 结构体的 Hash 特性并没有在 T 泛型参数上添加约束,因此 derive 属性的约束添加可以说是画蛇添足了。

Educe

「Educe」是笔者开发的进程式宏套件,可以用来加强原先 Rust 编程语言用 derive 属性来实作内置特性的方式,使得这类进程式宏可以在更多常见的场景下直接使用,让开发者不需要手动去写 impl 相关的程序。

Crates.io

Cargo.toml

educe = "*"

使用方法

Educe 目前能够实作的特性有 Debug、Clone、Copy、PartialEq、Eq、PartialOrd、Ord、Hash、Default、Deref、DerefMut、Into。

上面的实作 Hash 特性的例子可以很轻易地用 Educe 来改写,程序如下:

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq, Eq, Hash)]
pub struct Person {
    uid: u64,
    #[educe(Eq(ignore), Hash(ignore))]
    name: String,
    #[educe(Eq(ignore), Hash(ignore))]
    age: u8,
    #[educe(Eq(ignore), Hash(ignore))]
    score: f64,
}

struct NewType<T>(T);

impl<T> Hash for NewType<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        0u8.hash(state)
    }
}

#[derive(Educe)]
#[educe(Hash)]
struct B<T> {
    f1: NewType<T>,
}

// impl<T> Hash for B<T>, not impl<T: Hash> Hash for B<T>
特色

在预设的情形下,Educe 会激活所有有支持的特性。如果想要禁用它们的话,在 Cargo.toml 设置档中,可以不激活预设特性,只把自己想要用的特性加入 features 中来激活就好。

如下:

[dependencies.educe]
version = "*"
features = ["Debug", "Default", "Hash", "Clone", "Copy"]
default-features = false
Debug

在类型上加上 #[derive(Educe)] 和 #[educe(Debug)] 属性,就可以替该类型实作 Debug 特性。类型可以是任意结构体、任意枚举和任意联合(union)。此外,它还有支持类型名称、变体名称和字段名称的改变,也能够忽略掉指定的字段,还能够替指定的字段设置格式化时要使用的方法。更方便的是,它还能够把一般结构体当作元组结构体(tuple struct)来格式化,或是反过来把元组结构体当作一般结构体来格式化。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(Debug)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Debug)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
改变类型名称、变体名称或是字段名称

name 参数可以用来重命名一个类型、变体或是字段。如果你把它设为 false 则可以隐藏类型或变体的名称;把它设为 true 则可以强制显示名称。

use educe::Educe;

#[derive(Educe)]
#[educe(Debug(name(Struct2)))]
struct Struct {
    #[educe(Debug(name(f)))]
    f1: u8
}

#[derive(Educe)]
#[educe(Debug(name = true))]
enum Enum {
    #[educe(Debug(name = false))]
    V1,
    #[educe(Debug(name(V)))]
    V2 {
        #[educe(Debug(name(f)))]
        f1: u8,
    },
    #[educe(Debug(name = false))]
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(Educe)]
#[educe(Debug)]
struct Struct {
    #[educe(Debug(ignore))]
    f1: u8
}

#[derive(Educe)]
#[educe(Debug)]
enum Enum {
    V1,
    V2 {
        #[educe(Debug(ignore))]
        f1: u8,
    },
    V3(
        #[educe(Debug(ignore))]
        u8
    ),
}
元组结构体格式化成一般结构体,一般结构体格式化成元组结构体

named_field 属性可以用来设置类型或是变体下的字段是否要拥有名称。

use educe::Educe;

#[derive(Educe)]
#[educe(Debug(named_field = false))]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Debug)]
enum Enum {
    V1,
    #[educe(Debug(named_field = false))]
    V2 {
        f1: u8,
    },
    #[educe(Debug(named_field = true))]
    V3(
        u8,
        #[educe(Debug(name(value)))]
        i32
    ),
}
使用另外的方法来做格式化

method 参数可以被用在字段上,取代该字段的 Debug 特性实作,使该字段的类型不一定需要实作 Debug 特性。

use educe::Educe;

use std::fmt::{self, Formatter};

fn fmt<T>(_s: &T, f: &mut Formatter<'_>) -> fmt::Result {
    f.write_str("Hi")
}

#[derive(Educe)]
#[educe(Debug)]
enum Enum<T> {
    V1,
    V2 {
        #[educe(Debug(method(fmt)))]
        f1: u8,
    },
    V3(
        #[educe(Debug(method(std::fmt::UpperHex::fmt)))]
        u8,
        #[educe(Debug(method(fmt)))]
        T
    ),
}
泛型参数自动加上 Debug 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Debug 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Debug)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

use std::fmt::{self, Formatter};

fn fmt<D>(_s: &D, f: &mut Formatter<'_>) -> fmt::Result {
    f.write_str("Hi")
}

#[derive(Educe)]
#[educe(Debug(bound(T: std::fmt::Debug)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(Debug(method(fmt)))]
        f1: K,
    },
    V3(
        T
    ),
}

在上面的程序例子中,T 有绑定 Debug 特性,而 K 没有。

或者,我们也可以让 Educe 的行为跟 derive 属性一样,也就是替所有的泛型参数加上约束,不管结构体长怎样:

use educe::Educe;

#[derive(Educe)]
#[educe(Debug(bound(*)))]
struct Struct<T> {
    #[educe(Debug(ignore))]
    f: T,
}

这样的作法在我们不希望将特性实作成为永久公开 API 的一部分时会很有用。在上面这个例子中,Struct<T> 不会实作 Debug,除非 T 有实作 Debug。也就是说,即使现在不需要,它也有一个 T: Debug 的约束。以后我们可能会想要在用 Debug 来格式化的时候显示出 f 字段,到时候就不需要通过添加这个约束来进行破坏性 API 更改。

联合

联合并不会依照其字段的类型来做格式化,而是会将联合在内存中的值以 u8 切片的方式来格式化,因为我们无法在程序运行阶段知道当前的联合究竟是在用哪个字段。联合中的字段无法被省略、重命名或是用其它的方法来格式化。替联合类型实作 Debug 的方式是不安全的(unsafe),可能会暴露未经初始化的内存数据。

use educe::Educe;

#[derive(Educe)]
#[educe(Debug(unsafe))]
union Union {
    f1: u8,
    f2: i32,
}
Clone

在类型上加上 #[derive(Educe)] 和 #[educe(Clone)] 属性,就可以替该类型实作 Clone 特性。类型可以是任意结构体、任意枚举和任意联合。此外,它还能够替指定的字段设置在拷贝时要使用的方法。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(Clone)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Clone)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
使用另外的方法来做拷贝

method 参数可以被用在字段上,取代该字段的 Clone 特性实作。使该字段的类型不一定需要实作 Clone 特性。

use educe::Educe;

fn clone(v: &u8) -> u8 {
    v + 100
}

trait A {
    fn add(&self, rhs: u8) -> Self;
}

fn clone2<T: A>(v: &T) -> T {
    v.add(100)
}

#[derive(Educe)]
#[educe(Clone)]
enum Enum<T: A> {
    V1,
    V2 {
        #[educe(Clone(method(clone)))]
        f1: u8,
    },
    V3(
        #[educe(Clone(method(clone2)))]
        T
    ),
}
泛型参数自动加上 Clone 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Clone 特性的条件。如果 #[educe(Copy)] 属性存在,则是会加上必须实作 Copy 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Clone)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

trait A {
    fn add(&self, rhs: u8) -> Self;
}

fn clone<T: A>(v: &T) -> T {
    v.add(100)
}

#[derive(Educe)]
#[educe(Clone(bound(T: std::clone::Clone)))]
enum Enum<T, K: A> {
    V1,
    V2 {
        #[educe(Clone(method(clone)))]
        f1: K,
    },
    V3(
        T
    ),
}

在上面的程序例子中,T 有绑定 Clone 特性,而 K 没有。

或者,我们也可以使用 bound(*) 让 Educe 的行为跟 derive 属性一样,更详细的说明请见 Debug 小节。

use educe::Educe;

trait A {
    fn add(&self, rhs: u8) -> Self;
}

fn clone<T: A>(v: &T) -> T {
    v.add(100)
}

#[derive(Educe)]
#[educe(Clone(bound(*)))]
struct Struct<T: A> {
    #[educe(Clone(method(clone)))]
    f: T,
}
联合

联合的 Clone 特性实作请参考以下实作 Copy 特性的小节。

Copy

在类型上加上 #[derive(Educe)] 和 #[educe(Copy)] 属性,就可以替该类型实作 Copy 特性。类型可以是任意结构体、任意枚举和任意联合。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(Copy, Clone)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Copy, Clone)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
泛型参数自动加上 Copy 特性约束,或是手动设置其它约束

所有的泛型类型参数会自动被加上必须实作 Copy 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Copy, Clone)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

trait A {
    fn add(&self, rhs: u8) -> Self;
}

fn clone<T: A>(v: &T) -> T {
    v.add(100)
}

#[derive(Educe)]
#[educe(Copy, Clone(bound(T: Copy, K: A + Copy)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(Clone(method(clone)))]
        f1: K,
    },
    V3(
        T
    ),
}

请注意使用自己的方法来取代 Clone 特性的实作的话,对于又实作 Copy 特性的类型来说是不合适的。

联合

#[educe(Copy, Clone)] 属性可以被用在任意联合上。联合中的字段无法用其它的方法来拷贝。

use educe::Educe;

#[derive(Educe)]
#[educe(Copy, Clone)]
union Union {
    f1: u8,
}
PartialEq

在类型上加上 #[derive(Educe)] 和 #[educe(PartialEq)] 属性,就可以替该类型实作 PartialEq 特性。类型可以是任意结构体、任意枚举和任意联合。此外,它还能够忽略掉指定的字段,也能够替指定的字段设置在比较是否相同时要使用的方法。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(PartialEq)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq)]
struct Struct {
    #[educe(PartialEq(ignore))]
    f1: u8
}

#[derive(Educe)]
#[educe(PartialEq)]
enum Enum {
    V1,
    V2 {
        #[educe(PartialEq(ignore))]
        f1: u8,
    },
    V3(
        #[educe(PartialEq(ignore))]
        u8
    ),
}
使用另外的方法来做比较

method 参数可以被用在字段上,取代该字段的 PartialEq 特性实作。使该字段的类型不一定需要实作 PartialEq 特性。

use educe::Educe;

fn eq(a: &u8, b: &u8) -> bool {
    a + 1 == *b
}

trait A {
    fn is_same(&self, other: &Self) -> bool;
}

fn eq2<T: A>(a: &T, b: &T) -> bool {
    a.is_same(b)
}

#[derive(Educe)]
#[educe(PartialEq)]
enum Enum<T: A> {
    V1,
    V2 {
        #[educe(PartialEq(method(eq)))]
        f1: u8,
    },
    V3(
        #[educe(PartialEq(method(eq2)))]
        T
    ),
}
泛型参数自动加上 PartialEq 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 PartialEq 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

trait A {
    fn is_same(&self, other: &Self) -> bool;
}

fn eq<T: A>(a: &T, b: &T) -> bool {
    a.is_same(b)
}

#[derive(Educe)]
#[educe(PartialEq(bound(T: std::cmp::PartialEq, K: A)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(PartialEq(method(eq)))]
        f1: K,
    },
    V3(
        T
    ),
}

在上面的程序例子中,T 有绑定 PartialEq 特性,而 K 没有。

或者,我们也可以使用 bound(*) 让 Educe 的行为跟 derive 属性一样,更详细的说明请见 Debug 小节。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq(bound(*)))]
struct Struct<T> {
    #[educe(PartialEq(ignore))]
    f: T,
}
联合

#[educe(PartialEq(unsafe))] 属性可以被用在任意联合上。联合中的字段无法用其它的方法来比较。替联合类型实作 PartialEq 的方式是不安全的(unsafe),因为不会去检查联合究竟是使用哪个字段。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq(unsafe))]
union Union {
    f1: u8,
    f2: i32
}
Eq

在类型上加上 #[derive(Educe)] 和 #[educe(Eq)] 属性,就可以替该类型实作 Eq 特性。类型可以是任意结构体、任意枚举和任意联合。此外,它还能够忽略掉指定的字段,也能够替指定的字段设置在比较是否相同时要使用的方法。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq, Eq)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(PartialEq, Eq)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq, Eq)]
struct Struct {
    #[educe(Eq(ignore))]
    f1: u8
}

#[derive(Educe)]
#[educe(PartialEq, Eq)]
enum Enum {
    V1,
    V2 {
        #[educe(Eq(ignore))]
        f1: u8,
    },
    V3(
        #[educe(Eq(ignore))]
        u8
    ),
}
使用另外的方法来做比较

method 参数可以被用在字段上,取代该字段的 Eq 特性实作。使该字段的类型不一定需要实作 PartialEq 特性。

use educe::Educe;

fn eq(a: &u8, b: &u8) -> bool {
    a + 1 == *b
}

trait A {
    fn is_same(&self, other: &Self) -> bool;
}

fn eq2<T: A>(a: &T, b: &T) -> bool {
    a.is_same(b)
}

#[derive(Educe)]
#[educe(PartialEq, Eq)]
enum Enum<T: A> {
    V1,
    V2 {
        #[educe(Eq(method(eq)))]
        f1: u8,
    },
    V3(
        #[educe(Eq(method(eq2)))]
        T
    ),
}
泛型参数自动加上 PartialEq 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 PartialEq 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq, Eq)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

trait A {
    fn is_same(&self, other: &Self) -> bool;
}

fn eq<T: A>(a: &T, b: &T) -> bool {
    a.is_same(b)
}

#[derive(Educe)]
#[educe(PartialEq(bound(T: std::cmp::PartialEq, K: A)), Eq)]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(Eq(method(eq)))]
        f1: K,
    },
    V3(
        T
    ),
}
联合

#[educe(PartialEq(unsafe), Eq)] 属性可以被用在任意联合上。联合中的字段无法用其它的方法来比较。替联合类型实作 PartialEq 的方式是不安全的(unsafe),因为不会去检查联合究竟是使用哪个字段。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq(unsafe), Eq)]
union Union {
    f1: u8,
    f2: i32
}
PartialOrd

在类型上加上 #[derive(Educe)] 和 #[educe(PartialOrd)] 属性,就可以替该类型实作 PartialOrd 特性。类型可以是任意结构体和任意枚举。此外,它还能够忽略掉指定的字段,也能够替指定的字段设置在比较是否相同时要使用的方法。另外,变体和字段也都可以自订排列顺序。

基本用法
use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
struct Struct {
    f1: u8
}

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
struct Struct {
    #[educe(PartialOrd(ignore))]
    f1: u8
}

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
enum Enum {
    V1,
    V2 {
        #[educe(PartialOrd(ignore))]
        f1: u8,
    },
    V3(
        #[educe(PartialOrd(ignore))]
        u8
    ),
}
使用另外的方法来做比较

method 参数可以被用在字段上,取代该字段的 PartialOrd 特性实作。使该字段的类型不一定需要实作 PartialOrd 特性。

use educe::Educe;

use std::cmp::Ordering;

fn partial_cmp(a: &u8, b: &u8) -> Option<Ordering> {
    if a > b {
        Some(Ordering::Less)
    } else if a < b {
        Some(Ordering::Greater)
    } else {
        Some(Ordering::Equal)
    }
}

trait A {
    fn value(&self) -> u8;
}

fn partial_cmp2<T: A>(a: &T, b: &T) -> Option<Ordering> {
    partial_cmp(&a.value(), &b.value())
}

#[derive(Educe)]
#[educe(PartialEq, PartialOrd)]
enum Enum<T: A> {
    V1,
    V2 {
        #[educe(PartialOrd(method(partial_cmp)))]
        f1: u8,
    },
    V3(
        #[educe(PartialOrd(method(partial_cmp2)))]
        T
    ),
}
排列顺序

每个字段都可以加上 #[educe(PartialOrd(rank = priority_value))] 属性,其中的 priority_value 是一个整数,用来决定比较的优先级(priority_value 愈小就愈优先)。字段的 priority_value 默认值与其被定义的序数(也就是第几个字段)有关,会从 isize::MIN 开始算起。

use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
struct Struct {
    #[educe(PartialOrd(rank = 1))]
    f1: u8,
    #[educe(PartialOrd(rank = 0))]
    f2: u8,
}

对于变体,如果要改变其排列优先级,可以直接去设置它的判别值(discriminant)。

use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
#[repr(u8)]
enum Enum {
    Three { f1: u8 } = 3,
    Two(u8) = 2,
    One = 1,
}
泛型参数自动加上 PartialOrd 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 PartialOrd 特性的条件。

use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

use std::cmp::Ordering;

trait A {
    fn value(&self) -> u8;
}

fn partial_cmp<T: A>(a: &T, b: &T) -> Option<Ordering> {
    a.value().partial_cmp(&b.value())
}

#[derive(PartialEq, Educe)]
#[educe(PartialOrd(bound(T: std::cmp::PartialOrd, K: PartialEq + A)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(PartialOrd(method(partial_cmp)))]
        f1: K,
    },
    V3(
        T
    ),
}

在上面的程序例子中,T 有绑定 PartialOrd 特性,而 K 没有。

或者,我们也可以使用 bound(*) 让 Educe 的行为跟 derive 属性一样,更详细的说明请见 Debug 小节。

use educe::Educe;

#[derive(PartialEq, Educe)]
#[educe(PartialOrd(bound(*)))]
struct Struct<T> {
    #[educe(PartialOrd(ignore))]
    f: T,
}
Ord

在类型上加上 #[derive(Educe)] 和 #[educe(Ord)] 属性,就可以替该类型实作 Ord 特性。类型可以是任意结构体和任意枚举。此外,它还能够忽略掉指定的字段,也能够替指定的字段设置在比较是否相同时要使用的方法。另外,变体和字段也都可以自订排列顺序。

基本用法
use educe::Educe;

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
struct Struct {
    f1: u8
}

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
struct Struct {
    #[educe(Ord(ignore))]
    f1: u8
}

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
enum Enum {
    V1,
    V2 {
        #[educe(Ord(ignore))]
        f1: u8,
    },
    V3(
        #[educe(Ord(ignore))]
        u8
    ),
}
使用另外的方法来做比较

method 参数可以被用在字段上,取代该字段的 Ord 特性实作。使该字段的类型不一定需要实作 Ord 特性。

use educe::Educe;

use std::cmp::Ordering;

fn cmp(a: &u8, b: &u8) -> Ordering {
    if a > b {
        Ordering::Less
    } else if a < b {
        Ordering::Greater
    } else {
        Ordering::Equal
    }
}

trait A {
    fn value(&self) -> u8;
}

fn cmp2<T: A>(a: &T, b: &T) -> Ordering {
    cmp(&a.value(), &b.value())
}

#[derive(Educe)]
#[educe(PartialEq, Eq, PartialOrd, Ord)]
enum Enum<T: A> {
    V1,
    V2 {
        #[educe(Ord(method(cmp)))]
        f1: u8,
    },
    V3(
        #[educe(Ord(method(cmp2)))]
        T
    ),
}
排列顺序

每个字段都可以加上 #[educe(Ord(rank = priority_value))] 属性,其中的 priority_value 是一个整数,用来决定比较的优先级(priority_value 愈小就愈优先)。字段的 priority_value 默认值与其被定义的序数(也就是第几个字段)有关,会从 isize::MIN 开始算起。

use educe::Educe;

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
struct Struct {
    #[educe(Ord(rank = 1))]
    f1: u8,
    #[educe(Ord(rank = 0))]
    f2: u8,
}

对于变体,如果要改变其排列优先级,可以直接去设置它的判别值(discriminant)。

use educe::Educe;

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
#[repr(u8)]
enum Enum {
    Three { f1: u8 } = 3,
    Two(u8) = 2,
    One = 1,
}
泛型参数自动加上 Ord 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Ord 特性的条件。

use educe::Educe;

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

use std::cmp::Ordering;

trait A {
    fn value(&self) -> u8;
}

fn cmp<T: A>(a: &T, b: &T) -> Ordering {
    a.value().cmp(&b.value())
}

#[derive(PartialEq, Eq, Educe)]
#[educe(PartialOrd, Ord(bound(T: std::cmp::Ord, K: std::cmp::Ord + A)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(PartialOrd(method(cmp)))]
        f1: K,
    },
    V3(
        T
    ),
}
Hash

在类型上加上 #[derive(Educe)] 和 #[educe(Hash)] 属性,就可以替该类型实作 Hash 特性。类型可以是任意结构体、任意枚举和任意联合。此外,它还能够忽略掉指定的字段,也能够替指定的字段设置哈希时要使用的方法。

基本用法
use educe::Educe;

#[derive(Educe)]
#[educe(Hash)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Hash)]
enum Enum {
    V1,
    V2 {
        f1: u8,
    },
    V3(u8),
}
忽略字段

ignore 属性可以用来忽略指定的字段。

use educe::Educe;

#[derive(Educe)]
#[educe(Hash)]
struct Struct {
    #[educe(Hash(ignore))]
    f1: u8
}

#[derive(Educe)]
#[educe(Hash)]
enum Enum {
    V1,
    V2 {
        #[educe(Hash(ignore))]
        f1: u8,
    },
    V3(
        #[educe(Hash(ignore))]
        u8
    ),
}
使用另外的方法来做哈希

method 参数可以被用在字段上,取代该字段的 Hash 特性实作。使该字段的类型不一定需要实作 Hash 特性。

use educe::Educe;

use std::hash::{Hash, Hasher};

fn hash<H: Hasher>(_s: &u8, state: &mut H) {
    Hash::hash(&100, state)
}

fn hash2<H: Hasher, T>(_s: &T, state: &mut H) {
    Hash::hash(&100, state)
}

#[derive(Educe)]
#[educe(Hash)]
enum Enum<T> {
    V1,
    V2 {
        #[educe(Hash(method(hash)))]
        f1: u8,
    },
    V3(
        #[educe(Hash(method(hash2)))]
        T
    ),
}
泛型参数自动加上 Hash 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Hash 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Hash)]
enum Enum<T, K> {
    V1,
    V2 {
        f1: K,
    },
    V3(
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

use std::hash::{Hash, Hasher};

trait A {
    fn value(&self) -> u8;
}

fn hash<H: Hasher, T: A>(s: &T, state: &mut H) {
    Hash::hash(&s.value(), state)
}

#[derive(Educe)]
#[educe(Hash(bound(T: std::hash::Hash, K: A)))]
enum Enum<T, K> {
    V1,
    V2 {
        #[educe(Hash(method(hash)))]
        f1: K,
    },
    V3(
        T
    ),
}

在上面的程序例子中,T 有绑定 Hash 特性,而 K 没有。

或者,我们也可以使用 bound(*) 让 Educe 的行为跟 derive 属性一样,更详细的说明请见 Debug 小节。

use educe::Educe;

#[derive(Educe)]
#[educe(Hash(bound(*)))]
struct Struct<T> {
    #[educe(Hash(ignore))]
    f: T,
}
联合

#[educe(PartialEq(unsafe), Eq, Hash(unsafe))] 属性可以被用在任意联合上。联合中的字段无法用其它的方法来哈希。替联合类型实作 Hash 的方式是不安全的(unsafe),因为不会去检查联合究竟是使用哪个字段。

use educe::Educe;

#[derive(Educe)]
#[educe(PartialEq(unsafe), Eq, Hash(unsafe))]
union Union {
    f1: u8,
    f2: i32
}
Default

在类型上加上 #[derive(Educe)] 和 #[educe(Default)] 属性,就可以替该类型实作 Default 特性。类型可以是任意结构体、任意枚举和任意联合。此外,它还能直接指定整个类型的默认值,或是类型内特定字段的默认值。

基本用法

对于枚举和联合,您必须要再指派一个枚举的变体或是一个联合的字段来当作默认值,除非该枚举的变体数量或是联合的字段数量刚好只有一个。

use educe::Educe;

#[derive(Educe)]
#[educe(Default)]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Default)]
enum Enum {
    V1,
    #[educe(Default)]
    V2 {
        f1: u8,
    },
    V3(u8),
}

#[derive(Educe)]
#[educe(Default)]
union Union {
    f1: u8,
    #[educe(Default)]
    f2: f64,
}
整个类型的默认值
use educe::Educe;

#[derive(Educe)]
#[educe(Default(expression = Struct { f1: 1 }))]
struct Struct {
    f1: u8
}

#[derive(Educe)]
#[educe(Default(expression = Enum::Struct { f1: 1 }))]
enum Enum {
    Unit,
    Struct {
        f1: u8
    },
    Tuple(u8),
}

#[derive(Educe)]
#[educe(Default(expression = Union { f1: 1 }))]
union Union {
    f1: u8,
    f2: f64,
}

您可能会需要激活 full 特色来支持更高级的表达式解析。

指定字段的默认值
use educe::Educe;

#[derive(Educe)]
#[educe(Default)]
struct Struct {
    #[educe(Default = 1)]
    f1: u8,
    #[educe(Default = 11111111111111111111111111111)]
    f2: i128,
    #[educe(Default = 1.1)]
    f3: f64,
    #[educe(Default = true)]
    f4: bool,
    #[educe(Default = "Hi")]
    f5: &'static str,
    #[educe(Default = "Hello")]
    f6: String,
    #[educe(Default = 'M')]
    f7: char,
}

#[derive(Educe)]
#[educe(Default)]
enum Enum {
    Unit,
    #[educe(Default)]
    Tuple(
        #[educe(Default(expression = 0 + 1))]
        u8,
        #[educe(Default(expression = -11111111111111111111111111111 * -1))]
        i128,
        #[educe(Default(expression = 1.0 + 0.1))]
        f64,
        #[educe(Default(expression = !false))]
        bool,
        #[educe(Default(expression = "Hi"))]
        &'static str,
        #[educe(Default(expression = String::from("Hello")))]
        String,
        #[educe(Default(expression = 'M'))]
        char,
    ),
}

#[derive(Educe)]
#[educe(Default)]
union Union {
    f1: u8,
    f2: i128,
    f3: f64,
    f4: bool,
    #[educe(Default = "Hi")]
    f5: &'static str,
    f6: char,
}
泛型参数自动加上 Default 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Default 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Default)]
enum Enum<T> {
    Unit,
    #[educe(Default)]
    Struct {
        f1: T
    },
    Tuple(T),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

#[derive(Educe)]
#[educe(Default(bound(T: std::default::Default)))]
enum Enum<T> {
    Unit,
    #[educe(Default)]
    Struct {
        f1: T
    },
    Tuple(T),
}
new 关联函数

替类型加上 #[educe(Default(new))] 属性,可以使它拥有一个 new 关联函数。这个 new 关联函数会去调用 Default 特性的 default 关联函数。

use educe::Educe;

#[derive(Educe)]
#[educe(Default(new))]
struct Struct {
    f1: u8
}
Deref

在类型上加上 #[derive(Educe)] 和 #[educe(Deref)] 属性,就可以替该类型实作 Deref 特性。类型可以是任意结构体和任意枚举。

基本用法

您需要指定一个字段作为预设取得的不可变参考的字段,除非该结构体或是枚举的变体的字段数量刚好只有一个。

use educe::Educe;

#[derive(Educe)]
#[educe(Deref)]
struct Struct {
    f1: u8,
    #[educe(Deref)]
    f2: u8,
}

#[derive(Educe)]
#[educe(Deref)]
enum Enum {
    Struct {
        f1: u8
    },
    Struct2 {
        f1: u8,
        #[educe(Deref)]
        f2: u8,
    },
    Tuple(u8),
    Tuple2(
        u8,
        #[educe(Deref)]
        u8
    ),
}
DerefMut

在类型上加上 #[derive(Educe)] 和 #[educe(DerefMut)] 属性,就可以替该类型实作 DerefMut 特性。类型可以是任意结构体和任意枚举。

基本用法

您需要指定一个字段作为预设取得的可变参考的字段,除非该结构体或是枚举的变体的字段数量刚好只有一个。

use educe::Educe;

#[derive(Educe)]
#[educe(Deref, DerefMut)]
struct Struct {
    f1: u8,
    #[educe(Deref, DerefMut)]
    f2: u8,
}

#[derive(Educe)]
#[educe(Deref, DerefMut)]
enum Enum {
    Struct {
        f1: u8
    },
    Struct2 {
        f1: u8,
        #[educe(Deref, DerefMut)]
        f2: u8,
    },
    Tuple(u8),
    Tuple2(
        #[educe(DerefMut)]
        u8,
        #[educe(Deref)]
        u8
    ),
}

不可变参考字段和可变参考字段不一定要一样,但是它们的类型必须要是相同的。

Into

在类型上加上 #[derive(Educe)] 和 #[educe(Into(type))] 属性,就可以替该类型实作 Into<type> 特性。类型可以是任意结构体和任意枚举。

基本用法

您需要指定一个字段作为预设用来转换的字段,除非该结构体或是枚举的变体的字段数量刚好只有一个。如果没有指定,educe 也会先尝试寻找一个合适的字段。

use educe::Educe;

#[derive(Educe)]
#[educe(Into(u8), Into(u16))]
struct Struct {
    f1: u8,
    f2: u16,
}

#[derive(Educe)]
#[educe(Into(u8))]
enum Enum {
    V1 {
        f1: u8,
        #[educe(Into(u8))]
        f2: u8,
    },
    V2 (
        u8
    ),
}
使用另外的方法来做转换

method 参数可以被用在字段上,取代该字段的 Into 特性实作。使该字段的类型不一定需要实作 Into 特性。

use educe::Educe;

fn into(v: u16) -> u8 {
    v as u8
}

#[derive(Educe)]
#[educe(Into(u8))]
enum Enum {
    V1 {
        #[educe(Into(u8, method(into)))]
        f1: u16,
    },
    V2 (
        u8
    ),
}
泛型参数自动加上 Into 特性约束,或是手动设置其它约束

泛型类型参数在有需要的情况下会自动被加上必须实作 Into<type> 特性的条件。

use educe::Educe;

#[derive(Educe)]
#[educe(Into(u8))]
enum Enum<T, K> {
    V1 {
        f1: K,
    },
    V2 (
        T
    ),
}

或者,您也可以自行撰写 where 语法后的限定条件,如下:

use educe::Educe;

fn into<T>(_v: T) -> u8 {
    0
}

#[derive(Educe)]
#[educe(Into(u8, bound(K: Into<u8>)))]
enum Enum<T, K> {
    V1 {
        f1: K,
    },
    V2 (
        #[educe(Into(u8, method(into)))]
        T
    ),
}