4. 派生更多特质

您可以使用以下格式指定特性：#[opaque_typedef(derive(Trait1, Trait2, ...))]。

例如

#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, OpaqueTypedefUnsized)]
#[repr(C)]
#[opaque_typedef(derive(AsciiExt, AsMut(Deref, Self), AsRef(Deref, Self), DefaultRef, Deref,
                        DerefMut, Display, FromInner, Into(Arc, Box, Rc, Inner),
                        PartialEq(Inner, InnerRev, InnerCow, InnerCowRev, SelfCow, SelfCowRev),
                        PartialOrd(Inner, InnerRev, InnerCow, InnerCowRev, SelfCow, SelfCowRev)))]
#[opaque_typedef(allow_mut_ref)]
pub struct MyStr(str);

注意，某些特性可以被缩短。例如

• AsMutDeref可以写成AsMut(Deref)
• AsRefSelf可以写成AsRef(Self)
• IntoRc可以写成Into(Rc)
• PartialEqInner可以写成PartialEq(Inner)
• PartialOrdInner, PartialOrdSelfCow可以写成PartialOrd(Inner, SelfCow)

要查看“derive”可用项的列表，请阅读文档的其余部分或查看源代码（Derive 枚举在 opaque_typedef_macros/src/derives/mod.rs）。

要查看“derive”可用项的完整缩短表示法列表，请查看Derive::append_from_nested_names 方法在 opaque_typedef_macros/src/derives/mod.rs）。

4.1. 指定解引用目标（可选）

如果您指定了Deref、DerefMut、AsRefDeref或与Deref相关的其他内容，您还可以通过以下格式指定“解引用目标”：#[opaque_typedef(deref(...))]。

/// My owned string.
#[derive(Default, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, OpaqueTypedef)]
#[opaque_typedef(derive(AsMut(Deref, Inner), AsRef(Deref, Inner), Deref, DerefMut, Display,
                        FromInner, IntoInner, PartialEq(Inner, InnerRev),
                        PartialOrd(Inner, InnerRev)))]
#[opaque_typedef(deref(target = "str", deref = "String::as_str",
                       deref_mut = "String::as_mut_str"))]
#[opaque_typedef(allow_mut_ref)]
pub struct MyString {
    inner: String,
}

Opaque_typedef使用内部类型作为默认解引用目标类型，但您可以使用不同的类型，如上述示例所示。

• target:
  • 解引用目标类型。
• deref:
  • 从对内部类型的引用到对外部类型的引用的转换函数。
  • 该函数应实现 Fn(&Inner) -> &DerefTarget。
• deref_mut:
  • 从对内部类型的可变引用到对外部类型的可变引用的转换函数。
  • 该函数应实现 Fn(&mut Inner) -> &mut DerefTarget。

在示例中，AsMutInner 实现了 AsMut<String> for MyString，而 AsMutDeref 实现了 AsMut<str> for MyString。

如果您未指定 #[opaque_typedef(allow_mut_ref)]，则 deref_mut 不会被使用，您可以省略它。

5. 指定自定义验证器（可选）

您可以选择指定自定义验证器。在将内部类型转换为外部类型时，会验证内部类型的值。通过自定义验证器，您可以限制内部值。

要使用自定义验证器，请指定以下属性

• validator
  • 验证器函数。这应该具有如 Inner -> Result<Inner, Error> 的类型。
    • 对于有大小类型，Inner -> Result<Inner, Error>。验证器可以修改给定的值并返回修改后的值。
    • 对于无大小类型，&Inner -> Result<&Inner, Error>。
• error_type
  • 验证错误类型。通过 validator 指定的验证器应使用此类型作为错误。
  • 这不能是泛型，并且不能使用外部类型的任何类型参数。
• error_msg（可选）
  • 当验证失败时，在恐慌中显示错误信息。此值用于恐慌性转换失败时，例如，当将无效值传递给 Outer::from_inner（不是 Outer::try_from_inner）时。
  • 内部，如果 error_msg 缺失，则将使用 unwrap() 撒慌，如果指定了 error_msg，则将使用 expect(error_msg)。

以下示例来自 opaque_typedef_tests/src/even32.rs 和 opaque_typedef_tests/tests/even32.rs。

/// Even `i32`.
#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, OpaqueTypedef)]
#[opaque_typedef(derive(Binary, Deref, Display, FromInner, PartialEq(Inner, InnerRev),
                        PartialOrd(Inner, InnerRev), LowerHex, Octal, UpperHex))]
#[opaque_typedef(validation(validator = "validate_even32", error_type = "OddError",
                            error_msg = "Failed to create `Even32`"))]
pub struct Even32(i32);

impl Even32 {
    /// Returns the inner `i32` even value.
    pub fn to_i32(&self) -> i32 {
        self.0
    }
}

/// A type of an error indicating the integer is an odd number, not even.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct OddError;

fn validate_even32(v: i32) -> Result<i32, OddError> {
    if v % 2 == 0 {
        Ok(v)
    } else {
        Err(OddError)
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn ok() {
        let v = Even32::from(42);
        assert_eq!(v.to_i32(), 42);
    }

    #[test]
    #[should_panic]
    fn from_odd() {
        // Panics with message "Failed to create `Even32`: OddError".
        let _ = Even32::from(3);
    }
}

6. 指定自定义比较器（可选）

您可以为 PartialEq 和 PartialOrd 使用自定义实现。

要使用自定义比较器，请指定以下属性

• partial_eq
  • 部分相等函数。这应该具有如 &Inner -> &Inner -> bool 的类型。
• partial_ord
  • 部分顺序函数。它应该具有以下类型的函数，例如 &Inner -> &Inner -> Option<::std::cmp::Ordering>.
• ord
  • 全序函数。它应该具有以下类型的函数，例如 &Inner -> &Inner -> ::std::cmp::Ordering.
  • #[derive(Ord)] 没有使用 PartialOrd::partial_cmp 实现，因此它们可能会因错误而不一致。请记住要 保持它们（包括 PartialEq::eq）的一致性。

下面的示例取自 opaque_typedef_tests/src/reverse_order.rs 和 opaque_typedef_tests/tests/reverse_order.rs.

/// A wrapper type with reverse order.
#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Ord, Hash, OpaqueTypedef)]
#[opaque_typedef(derive(AsciiExt, AsMut(Deref), AsRef(Deref), Binary, Deref, DerefMut, Display,
                        FromInner, LowerHex, Octal, PartialOrdSelf, UpperHex))]
#[opaque_typedef(cmp(partial_ord = "(|a, b| PartialOrd::partial_cmp(a, b).map(|o| o.reverse()))",
                     ord = "(|a, b| Ord::cmp(a, b).reverse())"))]
#[opaque_typedef(allow_mut_ref)]
pub struct ReverseOrderSized<T>(pub T);


#[test]
fn reverse_i32() {
    use std::cmp::Ordering;
    assert_eq!(ReverseOrderSized(3i32).partial_cmp(&ReverseOrderSized(2i32)), Some(Ordering::Less));
    assert!(ReverseOrderSized(3i32) < ReverseOrderSized(2i32));
    assert_eq!(ReverseOrderSized(3i32).cmp(&ReverseOrderSized(2i32)), Ordering::Less);
    assert_eq!(ReverseOrderSized(3i32).cmp(&ReverseOrderSized(3i32)), Ordering::Equal);
    assert_eq!(ReverseOrderSized(3i32).cmp(&ReverseOrderSized(4i32)), Ordering::Greater);
}

特性

定义基本构造和转换

对于有大小类型

#[derive(OpaqueTypedef)] 实现了 opaque_typedef::OpaqueTypedef 特性，并有一些基本且有用的方法。

请参阅 https://docs.rs/opaque_typedef/*/opaque_typedef/trait.OpaqueTypedef.html 以获取详细信息。

对于无大小类型

#[derive(OpaqueTypedefUnsized)] 实现了 opaque_typedef::OpaqueTypedefUnsized 特性，并有一些基本且有用的方法。特别是 OpaqueTypedefUnsized::from_inner() 会非常有用。

请参阅 https://docs.rs/opaque_typedef/*/opaque_typedef/trait.OpaqueTypedefUnsized.html 以获取详细信息。

自动派生许多 std 特性

以下特性得到支持。

请注意，某些特性（如 DefaultRef）仅适用于有大小类型。

std::convert，类型转换

• As{Mut,Ref}{Deref,Inner,Self}
  • AsMutDeref 为 AsMut<DerefTarget> for Outer 实现。
  • AsMutInner 实现了 AsMut<Inner> for Outer.
  • AsMutSelf 实现了 AsMut<Outer> for Outer.
  • AsRefDeref 实现了 AsRef<DerefTarget> for Outer.
  • AsRefInner 实现了 AsRef<Inner> for Outer.
  • AsRefSelf 实现了 AsRef<Self> for Outer.
• Deref, DerefMut
  • Deref 实现了 std::ops::Deref for Outer.
  • DerefMut 实现了 std::ops::DerefMut for Outer.
• Into{Arc,Box,Inner,Rc}, FromInner
  • IntoArc 实现了 From<Outer> for Arc<Outer>（如果可能）或 Into<Arc<Outer>> for Outer.
  • IntoBox 实现了 From<Outer> for Box<Outer>（如果可能）或 Into<Box<Outer>> for Outer.
  • IntoInner 实现了 From<Outer> for Inner.
  • IntoRc 实现了 From<Outer> for Rc<Outer>（如果可能）或 Into<Rc<Outer>> for Outer.
  • FromInner 实现了 From<Inner> for Outer.

std::fmt

• std::fmt::*
  • Binary实现了std::fmt::Binary for Outer。
  • Display实现了std::fmt::Display for Outer。
  • LowerExp实现了std::fmt::LowerExp for Outer。
  • LowerHex实现了std::fmt::LowerHex for Outer。
  • Octal实现了std::fmt::Octal for Outer。
  • Pointer实现了std::fmt::Pointer for Outer。
  • UpperExp实现了std::fmt::UpperExp for Outer。
  • UpperHex实现了std::fmt::UpperHex for Outer。

std::cmp

• Partial{Eq,Ord}{Inner,InnerCow,SelfCow}{,Rev}
  • PartialEqInner实现了PartialEq<Inner> for Outer和类似的实现。
  • PartialEqInnerRev实现了PartialEq<Outer> for Inner和类似的实现。
    • 这是PartialEqInner的反转（操作数顺序交换）版本。
  • PartialEqInnerCow实现了PartialEq<Cow<Inner>> for Outer和类似的实现。
  • PartialEqInnerCowRev实现了PartialEq<Outer> for Cow<Inner>和类似的实现。
    • 这是PartialEqInnerCow的反转（操作数顺序交换）版本。
  • PartialEqSelf实现了PartialEq<Outer> for Outer和类似的实现。
    • 这与#[derive(PartialEq)]非常相似，但它在自定义比较时非常有用。
  • PartialEqSelfCow实现了PartialEq<Cow<Outer>> for Outer和类似的实现。
  • PartialEqSelfCowRev 实现了 PartialEq<Outer> for Cow<Outer> 和类似的实现。
    • 这是 PartialEqSelfCow 的反向版本（操作数顺序交换）。
  • PartialEqSelfCowAndInner 实现了 PartialEq<Cow<Outer>> for Inner 和类似的实现。
  • PartialEqSelfCowAndInnerCow 实现了 PartialEq<Inner> for Cow<Outer> 和类似的实现。
    • 这是 PartialEqSelfCowAndInner 的反向版本（操作数顺序交换）。
  • PartialOrdInner 实现了 PartialOrd<Inner> for Outer 和类似的实现。
  • PartialOrdInnerRev 实现了 PartialOrd<Outer> for Inner 和类似的实现。
    • 这是 PartialOrdInner 的反向版本（操作数顺序交换）。
  • PartialOrdInnerCow 实现了 PartialOrd<Cow<Inner>> for Outer 和类似的实现。
  • PartialOrdInnerCowRev 实现了 PartialOrd<Outer> for Cow<Inner> 和类似的实现。
    • 这是 PartialOrdInnerCow 的反向版本（操作数顺序交换）。
  • PartialOrdSelf 实现了 PartialOrd<Outer> for Outer 和类似的实现。
    • 这与 #[derive(PartialOrd)] 非常相似，但它将在自定义比较中非常有用。
  • PartialOrdSelfCow 实现了 PartialOrd<Cow<Outer>> for Outer 和类似的实现。
  • PartialOrdSelfCowRev 实现了 PartialOrd<Outer> for Cow<Outer> 和类似的实现。
    • 这是 PartialOrdSelfCow 的反向版本（操作数顺序交换）。
  • PartialOrdSelfCowAndInner 实现了 PartialOrd<Cow<Outer>>> for Inner 和类似的功能。
  • PartialOrdSelfCowAndInnerCow 实现了 PartialOrd<Inner> for Cow<Outer> 和类似的功能。
    • 这是 PartialOrdSelfCowAndInner 的反向（操作数顺序颠倒）版本。
• Ord
  • Ord 实现了 std::cmp::Ord for Outer。
    • 这与 #[derive(Ord)] 非常相似，但它将适用于自定义比较。

std::ops

• 一元运算符
  • 取负{,Ref}
  • 非{,Ref}
• 二元运算符
  • {加,按位与,按位或,按位异或,除,乘,取余,左移,右移,减}{,赋值}{,Ref}{Self,Inner,内部反转}

其他

• AsciiExt 实现了 std::ascii::AsciiExt for Outer。
• DefaultRef 实现了 Default for &Outer。

待办事项

• 更多特性
  • 仅在夜间可用的特性（TryFrom、TryInto 等）（#6）
• 支持具有多个字段的类型（#9）

许可证

根据您的选择，许可协议为以下之一：

• Apache License，版本 2.0，（LICENSE-APACHE.txt 或 https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT 许可证（LICENSE-MIT.txt 或 https://opensource.org/licenses/MIT）

。

贡献

除非您明确声明，否则根据 Apache-2.0 许可证定义，您有意提交的任何贡献，包括但不限于工作内容，都应作为上述双重许可发布，不附加任何额外条款或条件。