cast_trait_object

此包提供仅使用安全 Rust 和无平台特定代码在特例对象之间进行转换的功能。如果您想向下转换到具体类型而不是其他特例对象，则此包无法帮助您，而是使用 std::any 或类似 downcast-rs 的包。

此包提供两个功能，一个是抽象用于在特例对象之间进行转换的方法的特例 DynCast，以及一些宏以最小化实现此特例所需的样板代码。

用法

您应该在特例界限或作为超特例中使用 DynCast 特例，然后使用 DynCastExt 特例提供的方法进行转换。 DynCast 特例接受一个类型参数，该参数应由 create_dyn_cast_config 宏生成的 "config" 类型，此类型定义了从哪个特例到哪个特例进行转换。需要允许转换以满足 DynCast 特例界限的类型可以通过 impl_dyn_cast 宏实现它。

示例

use cast_trait_object::{create_dyn_cast_config, impl_dyn_cast, DynCast, DynCastExt};

create_dyn_cast_config!(SuperToSubCast = Super => Sub);
create_dyn_cast_config!(SuperUpcast = Super => Super);
trait Super: DynCast<SuperToSubCast> + DynCast<SuperUpcast> {}
trait Sub: Super {}

struct Foo;
impl Super for Foo {}
impl Sub for Foo {}
impl_dyn_cast!(Foo as Super => Sub, Super);

let foo: &dyn Super = &Foo;
// Casting to a sub trait is fallible (the error allows us to keep using the
// `dyn Super` trait object if we want which can be important if we are casting
// movable types like `Box<dyn Trait>`):
let foo: &dyn Sub = foo.dyn_cast().ok().unwrap();
// Upcasting to a supertrait is infallible:
let foo /*: &dyn Super*/ = foo.dyn_upcast::<dyn Super>();

通过 impl_dyn_cast 宏实现 DynCast 特例时，您还可以列出创建的 "config" 类型，而不是源特例和目标特例

impl_dyn_cast!(Foo => SuperToSubCast, SuperUpcast);

如果启用了 proc-macros 功能（默认情况下是启用的），我们还可以使用过程式属性宏来减少一些样板代码。

use cast_trait_object::{dyn_cast, dyn_upcast, DynCastExt};

#[dyn_cast(Sub)]
#[dyn_upcast]
trait Super {}
trait Sub: Super {}

struct Foo;
#[dyn_cast(Sub)]
#[dyn_upcast]
impl Super for Foo {}
impl Sub for Foo {}

请注意，#[dyn_upcast] 与 #[dyn_cast(Super)] 做的是同一件事，但它更清晰地表达了意图。

use cast_trait_object::{dyn_cast, DynCastExt};

#[dyn_cast(Super, Sub)]
trait Super {}
trait Sub: Super {}

struct Foo;
#[dyn_cast(Super, Sub)]
impl Super for Foo {}
impl Sub for Foo {}

let foo: &dyn Sub = &Foo;
// Upcasting still works:
let foo /*: &dyn Super*/ = foo.dyn_upcast::<dyn Super>();

泛型

泛型特性和类型受到支持，并且声明性宏（impl_dyn_cast、create_dyn_cast_config、impl_dyn_cast_config）和过程式属性宏（dyn_cast 和 dyn_upcast）都可以与泛型一起使用。

use cast_trait_object::{DynCastExt, dyn_cast, dyn_upcast};

// Define a source and target trait:
#[dyn_cast(Sub<T>)]
#[dyn_upcast]
trait Super<T> {}
trait Sub<T>: Super<T> {}

// Since `T` isn't used for `Color` it doesn't need to be `'static`:
struct Color(u8, u8, u8);
#[dyn_cast(Sub<T>)]
#[dyn_upcast]
impl<T> Super<T> for Color {}
impl<T> Sub<T> for Color {}

struct Example<T>(T);
#[dyn_cast(Sub<T>)]
#[dyn_upcast]
impl<T: 'static> Super<T> for Example<T> {}
impl<T: 'static> Sub<T> for Example<T> {}

let as_sub: &dyn Sub<bool> = &Example(false);
let upcasted: &dyn Super<bool> = as_sub.dyn_upcast();
let _downcasted /*: &dyn Sub<bool> */ = upcasted.dyn_cast::<dyn Sub<bool>>().ok().unwrap();

请注意，当前对泛型类型的支持有一个限制，即如果实现 DynCast 的类型有任何泛型类型参数，则它们可能需要被约束为 'static。

泛型类型还有一个限制，这可能有点反直观。由宏生成的 DynCast 实现必须始终成功或始终失败。这意味着，如果目标特性只为 DynCast 特性实现的类型子集实现，则转换将始终失败。

use cast_trait_object::{create_dyn_cast_config, impl_dyn_cast, DynCast, DynCastExt};

// Define a source and target trait:
create_dyn_cast_config!(UpcastConfig = Super => Super);
create_dyn_cast_config!(SuperConfig = Super => Sub);
trait Super: DynCast<SuperConfig> + DynCast<UpcastConfig> {}
trait Sub: Super {}

/// Only implements `Sub` for types that implement `Display`.
struct OnlyDisplayGeneric<T>(T);
impl<T: 'static> Super for OnlyDisplayGeneric<T> {}
impl<T: core::fmt::Display + 'static> Sub for OnlyDisplayGeneric<T> {}
// The cast to `Sub` will always fail since this impl of DynCast includes
// some `T` that don't implement `Display`:
impl_dyn_cast!(for<T> OnlyDisplayGeneric<T> as Super where {T: 'static} => Sub);
impl_dyn_cast!(for<T> OnlyDisplayGeneric<T> as Super where {T: 'static} => Super);

// &str does implement Display:
let _is_display: &dyn core::fmt::Display = &"";

// But the cast will still fail:
let as_super: &dyn Super = &OnlyDisplayGeneric("");
assert!(as_super.dyn_cast::<dyn Sub>().is_err());

// `OnlyDisplayGeneric<&str>` does implement `Sub`:
let as_sub: &dyn Sub = &OnlyDisplayGeneric("");

// Note that this means that we can perform an upcast and then fail to downcast:
let upcasted: &dyn Super = as_sub.dyn_upcast();
assert!(upcasted.dyn_cast::<dyn Sub>().is_err());

避免这种问题的最佳方法是使源特性实现和目标特性实现都具有相同的特性行界。

工作原理

转换是如何进行的

将 DynCast 特性作为超特性添加到特性对象v表中，这为特性对象添加了一些额外的方法。这些方法本质上都是接收一个类型指针，返回一个新的胖指针，该指针指向所需的v表。由于我们需要为每种类型的特性对象生成一个，因此需要为 &dyn Trait、&mut dyn Trait、Box<dyn Trait>、Rc<dyn Trait> 和 Arc<dyn Trait> 每种类型生成一个方法。请注意，这些方法完全是安全的Rust代码，这个crate不使用或生成任何不安全的代码。

trait Super {}
trait Sub {
    fn upcast(self: Box<Self>) -> Box<dyn Super>;
}

impl Super for () {}
impl Sub for () {
    fn upcast(self: Box<Self>) -> Box<dyn Super> { self }
}

let a: Box<dyn Sub> = Box::new(());
let a: Box<dyn Super> = a.upcast();

trait Source {}
trait Target {}

struct Foo;
impl Source for Foo {}

struct Fallback;
impl Fallback {
    fn cast<'a, T: Source>(&self, value: &'a T) -> &'a dyn Source { value }
}

struct HasTrait<T>(core::marker::PhantomData<T>);
impl<T> HasTrait<T> {
    fn new() -> Self {
         Self(core::marker::PhantomData)
    }
}
impl<T: Target> HasTrait<T> {
    fn cast<'a>(&self, value: &'a T) -> &'a dyn Target { value }
}
impl<T> core::ops::Deref for HasTrait<T> {
    type Target = Fallback;
    fn deref(&self) -> &Self::Target {
        static FALLBACK: Fallback = Fallback;
        &FALLBACK
    }
}

let used_fallback: &dyn Source = HasTrait::<Foo>::new().cast(&Foo);