Struct emplacable::Emplacable

#[repr(transparent)]
pub struct Emplacable<T, F>where
    T: ?Sized,
    F: EmplacableFn<T>,{ /* private fields */ }

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.

How it works

To make an Emplacable<T, _>, you must first produce an EmplacableFn<T>, which is an FnOnce that accepts an Emplacer<T>. Your EmplacableFn<T> perform the follwoing steps:

1. Call into_fn on the Emplacer<T> to obtain a EmplacerFn<T>, which is an alias for dyn FnMut(Layout, <T as Pointee>::Metadata, &mut (dyn FnMut(*mut PhantomData<T>))).

2. Call the EmplacerFn<T> with the following arguments:

   1. Layout: The layout of the value of type T you want to emplace
   2. <T as Pointee>::Metadata: The pointer metadata of the value of type T you want to emplace
   3. &mut (dyn FnMut(*mut PhantomData<T>))): The closure you must pass for this thrid argument must do one of two things, depending on the *mut PhantomData<T> pointer it recieves.
      • if the pointer is null, it should drop the value of type T.
      • otherwise, it should write the value of type T to the pointer, which it can assume points to the start of an allocation with the size and alignment of the Layout from above.

Once you have an EmplacableFn<T>, use Emplacable::from_fn to turn it into an Emplacable<T, _>.

There are safety preconditions at every step of this process that must be respected to avoid UB. Read the documentation of all the methods involved to learn about them.

Implementations

impl<T, F> Emplacable<T, F>where T: ?Sized, F: EmplacableFn<T>,

pub unsafe fn from_fn(closure: F) -> Self

Create a new Emplacable from a closure. This is only useful if you are implementing a function that returns an unsized value as an Emplacable.

Safety

The closure closurse must, either diverge without returning, or, if it returns, then it must have used the emplacer to fully initalize the value.

pub fn into_fn(self) -> F

Returns the closure inside this Emplacable.

This is only useful if you are implementing a function like box_new_with.

pub fn get(self) -> Twhere T: Sized,

Emplaces this sized T onto the stack.

pub fn forget(self)

Runs the Emplacable closure, but doesn’t run the “inner closure”, so the value of type T is forgotten, and its destructor is not run.

If you want to drop the T and run its destructor, drop the Emplacable instead.

pub fn unsize<U: ?Sized>(self) -> Emplacable<U, impl EmplacableFn<U>>where T: Sized + Unsize<U>,

Turns an emplacer for a sized type into one for an unsized type via an unsizing coercion (for example, array -> slice or concrete type -> trait object).

pub fn from_iter<I>(iter: I) -> Emplacable<[T], impl EmplacableFn<[T]>>where T: Sized, I: IntoIterator<Item = Self>, I::IntoIter: ExactSizeIterator,

Creates an Emplacable for a slice of values of type T out of an iterator of values of type T.

This function differs from FromIterator::from_iter in that the iterator is required to be an ExactSizeIterator. If ExactSizeIterator is incorrectly implemented, this function may panic or otherwise misbehave (but will not trigger UB).

impl<T, F> Emplacable<[T], F>where F: EmplacableFn<[T]>,

pub fn into_vec(self) -> Vec<T>

Turns this emplacer for a slice of Ts into an owned Vec<T>.

impl<F> Emplacable<str, F>where F: EmplacableFn<str>,

pub fn into_string(self) -> String

Turns this emplacer for a string slice into an owned, heap-allocated String.

Trait Implementations

impl<T, F> Drop for Emplacable<T, F>where T: ?Sized, F: EmplacableFn<T>,

fn drop(&mut self)

Runs the contained closure to completion, instructing it to drop the value of type T.

impl<T, F> Extend<Emplacable<T, F>> for Vec<T>where F: EmplacableFn<T>,

fn extend<I>(&mut self, iter: I)where I: IntoIterator<Item = Emplacable<T, F>>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'s, T: Clone + 's> From<&'s [T]> for Emplacable<[T], <&'s [T] as IntoEmplacable<[T]>>::Closure>

fn from(value: &'s [T]) -> Self

Converts to this type from the input type.

impl<'s> From<&'s CStr> for Emplacable<CStr, <&'s CStr as IntoEmplacable<CStr>>::Closure>

fn from(value: &'s CStr) -> Self

Converts to this type from the input type.

impl<'s> From<&'s OsStr> for Emplacable<OsStr, <&'s OsStr as IntoEmplacable<OsStr>>::Closure>

fn from(value: &'s OsStr) -> Self

Converts to this type from the input type.

impl<'s> From<&'s Path> for Emplacable<Path, <&'s Path as IntoEmplacable<Path>>::Closure>

fn from(value: &'s Path) -> Self

Converts to this type from the input type.

impl<'s> From<&'s str> for Emplacable<str, <&'s str as IntoEmplacable<str>>::Closure>

fn from(value: &'s str) -> Self

Converts to this type from the input type.

impl<T, const N: usize, F> From<[Emplacable<T, F>; N]> for Emplacable<[T], <[Emplacable<T, F>; N] as IntoEmplacable<[T]>>::Closure>where F: EmplacableFn<T>,

fn from(value: [Emplacable<T, F>; N]) -> Self

Converts to this type from the input type.

impl<T, const N: usize, F> From<[Emplacable<T, F>; N]> for Emplacable<[T; N], <[Emplacable<T, F>; N] as IntoEmplacable<[T; N]>>::Closure>where F: EmplacableFn<T>,

fn from(value: [Emplacable<T, F>; N]) -> Self

Converts to this type from the input type.

impl<T: ?Sized> From<Box<T, Global>> for Emplacable<T, <Box<T> as IntoEmplacable<T>>::Closure>

fn from(value: Box<T>) -> Self

Converts to this type from the input type.

impl<T, F> From<Emplacable<[T], F>> for Vec<T>where F: EmplacableFn<[T]>,

fn from(emplacable: Emplacable<[T], F>) -> Self

Converts to this type from the input type.

impl<T, const N: usize, F> From<Emplacable<[T; N], F>> for Emplacable<[T], <Emplacable<[T; N], F> as IntoEmplacable<[T]>>::Closure>where F: EmplacableFn<[T; N]>,

fn from(value: Emplacable<[T; N], F>) -> Self

Converts to this type from the input type.

impl<F> From<Emplacable<CStr, F>> for CStringwhere F: EmplacableFn<CStr>,

fn from(emplacable: Emplacable<CStr, F>) -> Self

Converts to this type from the input type.

impl<F> From<Emplacable<OsStr, F>> for OsStringwhere F: EmplacableFn<OsStr>,

fn from(emplacable: Emplacable<OsStr, F>) -> Self

Converts to this type from the input type.

impl<F> From<Emplacable<Path, F>> for PathBufwhere F: EmplacableFn<Path>,

fn from(emplacable: Emplacable<Path, F>) -> Self

Converts to this type from the input type.

impl<T, F> From<Emplacable<T, F>> for Arc<T>where T: ?Sized, F: EmplacableFn<T>,

fn from(emplacable: Emplacable<T, F>) -> Self

Converts to this type from the input type.

impl<T, F> From<Emplacable<T, F>> for Rc<T>where T: ?Sized, F: EmplacableFn<T>,

fn from(emplacable: Emplacable<T, F>) -> Self

Converts to this type from the input type.

impl<F> From<Emplacable<str, F>> for Emplacable<[u8], <Emplacable<str, F> as IntoEmplacable<[u8]>>::Closure>where F: EmplacableFn<str>,

fn from(emplacable: Emplacable<str, F>) -> Self

Converts to this type from the input type.

impl<F> From<Emplacable<str, F>> for Stringwhere F: EmplacableFn<str>,

fn from(emplacable: Emplacable<str, F>) -> Self

Converts to this type from the input type.

impl<T> From<T> for Emplacable<T, <T as IntoEmplacable<T>>::Closure>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T> From<Vec<T, Global>> for Emplacable<[T], <Vec<T> as IntoEmplacable<[T]>>::Closure>

fn from(value: Vec<T>) -> Self

Converts to this type from the input type.

impl<T, F> FromIterator<Emplacable<T, F>> for Vec<T>where F: EmplacableFn<T>,

fn from_iter<I>(iter: I) -> Selfwhere I: IntoIterator<Item = Emplacable<T, F>>,

Creates a value from an iterator.