Struct emplacable::Emplacable
source · pub struct Emplacable<T, F>where
T: ?Sized,
F: EmplacableFn<T>,{ /* private fields */ }
Expand description
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:
-
Call
into_fn
on theEmplacer<T>
to obtain aEmplacerFn<T>
, which is an alias fordyn FnMut(Layout, <T as Pointee>::Metadata, &mut (dyn FnMut(*mut PhantomData<T>)))
. -
Call the
EmplacerFn<T>
with the following arguments:Layout
: The layout of the value of typeT
you want to emplace<T as Pointee>::Metadata
: The pointer metadata of the value of typeT
you want to emplace&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 theLayout
from above.
- if the pointer is null, it should drop the value of type
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§
source§impl<T, F> Emplacable<T, F>where
T: ?Sized,
F: EmplacableFn<T>,
impl<T, F> Emplacable<T, F>where
T: ?Sized,
F: EmplacableFn<T>,
sourcepub unsafe fn from_fn(closure: F) -> Self
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.
sourcepub fn into_fn(self) -> F
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
.
sourcepub fn forget(self)
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.
sourcepub fn unsize<U: ?Sized>(self) -> Emplacable<U, impl EmplacableFn<U>>
pub fn unsize<U: ?Sized>(self) -> Emplacable<U, impl EmplacableFn<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).
sourcepub fn from_iter<I>(iter: I) -> Emplacable<[T], impl EmplacableFn<[T]>>
pub fn from_iter<I>(iter: I) -> Emplacable<[T], impl EmplacableFn<[T]>>
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).
source§impl<T, F> Emplacable<[T], F>where
F: EmplacableFn<[T]>,
impl<T, F> Emplacable<[T], F>where
F: EmplacableFn<[T]>,
source§impl<F> Emplacable<str, F>where
F: EmplacableFn<str>,
impl<F> Emplacable<str, F>where
F: EmplacableFn<str>,
sourcepub fn into_string(self) -> String
pub fn into_string(self) -> String
Turns this emplacer for a string slice into an owned, heap-allocated String
.
Trait Implementations§
source§impl<T, F> Drop for Emplacable<T, F>where
T: ?Sized,
F: EmplacableFn<T>,
impl<T, F> Drop for Emplacable<T, F>where
T: ?Sized,
F: EmplacableFn<T>,
source§impl<T, F> Extend<Emplacable<T, F>> for Vec<T>where
F: EmplacableFn<T>,
impl<T, F> Extend<Emplacable<T, F>> for Vec<T>where
F: EmplacableFn<T>,
source§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = Emplacable<T, F>>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = Emplacable<T, F>>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)