Trait gazebo::coerce::Coerce

source · [−]
pub unsafe trait Coerce<To: ?Sized> { }
Expand description

A marker trait such that the existence of From: Coerce<To> implies that From can be treat as To without any data manipulation. Particularly useful for containers, e.g. Vec<From> can be treated as Vec<To> in O(1). If such an instance is available, you can use coerce to perform the conversion.

Importantly, you must make sure Rust does not change the type representation between the different types (typically using a repr directive), and it must be safe for the From to be treated as To, namely same (or less restrictive) alignment, no additional invariants, value can be dropped as To.

One use of Coerce is around newtype wrappers:

use gazebo::coerce::{Coerce, coerce};
#[repr(transparent)]
#[derive(Debug, Coerce)]
struct Wrapper(String);

let value = vec![Wrapper("hello".to_owned()), Wrapper("world".to_owned())];
assert_eq!(
    coerce::<_, &Vec<String>>(&value).join(" "),
    "hello world"
);
let mut value = coerce::<_, Vec<String>>(value);
assert_eq!(value.pop(), Some("world".to_owned()));

Another involves containers:

use gazebo::coerce::{Coerce, coerce};
#[derive(Coerce)]
#[repr(C)]
struct Container<T>(i32, T);

let value = Container(20, Wrapper("twenty".to_owned()));
assert_eq!(
    coerce::<_, &Container<String>>(&value).1,
    "twenty"
);

If you only need coerce on newtype references, then the ref-cast crate provides that, along with automatic derivations (no unsafe required).

Implementations on Foreign Types

Implementors