unsize

Goals and Targets

In embedded environments there are quite many use cases for custom smart pointers, for example to encapsulate ownership of objects on the stack or within a custom arena etc. One also wants to avoid unnecessary monomorphization that is for code size it is often desirable to use a dynamic trait object as indirection instead of instantiating a generic for a great number of type parameters. However, these can not be allocated (or often even constructed) directly. The standard library Box usually provides a sort of coercion: You can convert Box<[T; N]> to Box<[T]> for all array sizes or Box<u32> to Box<dyn Any>.

However, this does not work for custom smart pointers. The conversion is based on a nightly-only trait that one needs to explicitly opt-in to. This crate provides an alternative that works with no_std environments, for example to enable custom Box designs that avoid any dependency on a global allocator, or an arena based reference counted pointer, etc. For these use cases it is intended to replace the nightly unsizing mechanism with a stable and safe solution.

Usage

As a library developer you can implement the CoerciblePtr trait for your smart pointer type. This enables the use of all coercions with this pointer type. To provide custom unsize coercions to your own ?Sized wrapper type you can provide a safe constructor for Coercion.

As a user of a unsize-enabled pointer type, you should import the CoerceUnsize extension trait and the Coercion marker type. Then create an instance of Coercion to 'coerce' the pointee type of a smart pointer. The type defines a number of safe constructors and an unsafe escape hatch. The crate further defines a macro that provides safe coercion to other unsized types, if it compiles.

Additional

This project is licensed under Zlib OR Apache-2.0 OR MIT. You may alternatively choose the Unlicense instead in which case the copyright headers signify the parts dedicated to the public domain to the fullest possible extent instead.