Crate emplacable

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]	Emplacable<[i32], _>	with_emplacable_for
[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.

Macros

by_value_str

Construct a str from a string literal, in its dereferenced form.

unsize

Helper for coercing values to unsized types.

Structs

Emplacable

A wrapped closure that you can pass to functions like box_new_with, that describes how to write a value of type T to a caller-provided allocation. You can get a T out of an Emplacable through functions like box_new_with. Alternately, you can drop the value of type T by dropping the Emplacable. Or you can forget the value of type T with Emplacable::forget.

Emplacer

Passed as the last argument to Emplacable closures. Wraps a closure that tells the function where to write its return value.

Traits

EmplacableFn

Alias of for<'a> FnOnce(&'a mut Emplacer<T>).

Functions

arc_new

Like Arc::new, but T can be ?Sized.

arc_new_with

Like Arc::new, but takes an Emplacer<T, _> instead of T directly.

arc_pin

Like Arc::pin, but T can be ?Sized.

arc_pin_with

Like Arc::pin, but takes an Emplacer<T, _> instead of T directly.

box_new

Like Box::new, but T can be ?Sized.

box_new_with

Like Box::new, but takes an Emplacer<T, _> instead of T directly.

box_pin

Like Box::pin, but T can be ?Sized.

box_pin_with

Like Box::pin, , but takes an Emplacer<T, _> instead of T directly.

rc_new

Like Rc::new, but T can be ?Sized.

rc_new_with

Like Rc::new, but takes an Emplacer<T, _> instead of T directly.

rc_pin

Like Rc::pin, but T can be ?Sized.

rc_pin_with

Like Rc::pin, but takes an Emplacer<T, _> instead of T directly.

with_emplacable_for

Accepts a possibly-unsized value as a first argument, turns it into an Emplacable, and passes the emplacer to the given closure.

Type Aliases

EmplacerFn

The type of the closure that Emplacer<'a, T> wraps.

WithEmplacableForFn

EmplacableFn used by with_emplacable_for.