traitcastrs

Requirements

This crate requires a nightly compiler.

What can this crate do?

This crate adds the TraitcastableAny replacement trait for Any. It can be used exactly like the Any trait for downcasting to a concrete type. With the trait_upcasting feature you can even cast any &dyn TraitcastableAny to &dyn Any. Additionally the TraitcastableAny trait allows you to directly downcast to other &dyn Traits.

To make this work you must specify all target traits you want to be able to downcast to in the make_trait_castable(Trait1, Trait2, ...) attribute macro. This macro can be applied to structs, enums and unions. It implements the TraitcastableAny trait for your struct, enum or union.

Note: No modifications on the target traits is necessary. Which allows you to downcast to traits of other libraries you don't control.

Usage

Add the trait_cast_rs crate to your Cargo.toml and switch to a nightly compiler.
Add the #[make_trait_castable(Trait1, Trait2, ...)] macro to your struct/enum/union. List all traits you eventually want to be able to downcast to. You must implement all listed traits.
Use references to dyn TraitcastableAny throughout your code instead of dyn Any.
Enjoy downcasting to trait objects.

Example

```rust use traitcastrs::{ maketraitcastable, TraitcastableAny, TraitcastableAnyInfra, TraitcastableAnyInfraExt, };

[maketraitcastable(Print)]

struct Source(i32); trait Print { fn print(&self); } impl Print for Source { fn print(&self) { println!("{}", self.0) } }

let source = Box::new(Source(5)); let castable: Box = source; let x: &dyn Print = castable.downcast_ref().unwrap(); x.print(); ```

EVEN MORE Examples 🔥

Check out the examples.

If you want to do something the make_trait_castable attribute macro can't handle (like implementing for generic structs - pull requests are open) check out the manual*.rs examples.

There is also a decl marco available - check out the with_decl_macro*.rs examples.

Premature Optimization

The order of the parameters for make_trait_castable determines the lookup order. So you should order them according to the downcast frequency. With the most frequent traits first.

Authors

raldone01 and onestacked are the primary authors and maintainers of this library.

License

This project is released under either:

at your choosing.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

How it works

I will give you a quick rundown of our internal operations: 💦

Compile time:

Add a casting function for every downcast path to the concrete type. This function gets a dyn TraitcastableAny, which it then downcasts to a concrete type using Any in the background. In the last step it casts the concrete type to the wanted trait object and returns it.
Add a traitcast_targets function that returns a const slice of (typeid, transmuted casting function ptr).

Runtime: Get targets array -> Find the target typeid -> Transmute function pointer back to original type -> Call the function pointer to get the wanted trait object -> return it -> 💲 profit 💲

SAFETY 🏰

The unchecked variants of the downcast function all use unsafe - expectedly.
The only other use of unsafe is the transmutation of function pointers. However when they are called the are transmuted back to their original type. So this should be 105% save. ~~As long as typeids don't collide.~~

Alternatives (and why our crate is the best)

This alternatives section is not exhaustive for a more objective/detailed comparison see the alternatives section of casttraitobject.

mopa: Had its last update 6 years ago. Has some unresolved unsoundness issues. Also requires modifications on traits themselves while we just modify the struct/enum/union (see note above).
mopa-maintained: Might have fixed some issues but still has an old code base with just a version bump.
traitcast: Has no readme on crates.io. Uses a GLOBAL REGISTRY with lazy_static. To be fair it allows you to use the default Any and doesn't require nightly.

TODO: Remove this section once our last update is 6 years old.