#unsized #placement-new

nightly no-std emplacable

Return unsized values from functions

1 unstable release

Uses new Rust 2021

0.1.0-alpha.5 Nov 2, 2022
0.1.0-alpha.4 Oct 30, 2022
0.1.0-alpha.2 Oct 29, 2022

#715 in Rust patterns

Download history 119/week @ 2022-10-28 34/week @ 2022-11-04 12/week @ 2022-11-11 8/week @ 2022-11-18 8/week @ 2022-11-25

74 downloads per month
Used in unsized-vec

MIT/Apache

62KB
976 lines

emplacable

docs.rs Crates.io

Return values of unsized types, like [i32] or dyn Any, from functions, with a mechanism similar to placement new.

Written to support the unsized-vec crate, but is independent of it. Experimental, and requires nightly Rust.


lib.rs:

Machinery to support functions that return unsized values.

Written to support the unsized-vec crate, but is independent of it. Requires nightly Rust.

Unsized values can take many forms:

  • On stable Rust, values of unsized types like [str], [u8], and dyn Any are generally encountered behind a pointer, like &str or Box<dyn Any>.

  • Nightly Rust provides limited support for passing unsized values by value as arguments to functions, using the unsized_fn_params feature. There is also unsized_locals, for storing these values on the stack using alloca. (However, that feature is "incomplete" and this crate doesn't make use of it). But even with thse two feature gates enabled, functions cannot return unsized values directly. Also, the only way to produce a by-value unsized value in today's Rust is by dereferencing a [Box]; this crate provides the unsize macro to work around this limitation.

  • For functions that return unsized values, this crate provides the [Emplacable] type. Functions that want to return a value of type T, where T is unsized, return an Emplacable<T, _> instead. Emplacable<T> wraps a closure; that closure contains instructions for writing out a T to a caller-provided region of memory. Other functions accept the Emplacable as an argument and call its contained closure to write out the T to some allocation provided by them. For example, this crate provides the [box_new_with] function, which turns an Emplacable<T> into a [Box<T>].

Converting between types

I have I want I can use
[i32; 2] [i32] unsize
[i32; 2] Emplacable<[i32; 2], _> [Into::into]
[i32] Box<[i32]> [box_new]
Box<[i32; 2]> Box<[i32]> CoerceUnsized
Box<[i32]> [i32] dereference the box with *
Box<[i32]> Emplacable<[i32], _> [Into::into]
Vec<i32> Emplacable<[i32], _> [Into::into]
Emplacable<[i32; 2], _> [i32; 2] [Emplacable::get]
Emplacable<[i32; 2], _> Emplacable<[i32], _> [Into::into]
Emplacable<[i32; 2], _> Emplacable<dyn Debug, _> [Emplacable::unsize]
Emplacable<[i32], _> Box<[i32]> [box_new_with]
Emplacable<[i32], _> Vec<i32> [Into::into]
Emplacable<[i32], _> Rc<[i32]> [Into::into]
Emplacable<[i32], _> Arc<[i32]> [Into::into]
&[i32] Box<[i32]> [Into::into]
&[i32] Emplacable<[i32], _> [Into::into]

You can replace [i32; 2] and [i32] above by any pair of types (T, U) such that T: Unsize<U>.

A note on examples

This crate has very few examples, as it provides tools to work with unsized types but no fun things that use the tools. If you want more usage examples, check out unsized-vec's documentation and the examples folder on GitHub.

No runtime deps

Features

  • alloc
  • std