Trait core::clone::CloneToUninit

source · 
pub unsafe trait CloneToUninit {
    // Required method
    unsafe fn clone_to_uninit(&self, dst: *mut Self);
}
🔬This is a nightly-only experimental API. (clone_to_uninit #126799)
Expand description

A generalization of Clone to dynamically-sized types stored in arbitrary containers.

This trait is implemented for all types implementing Clone, and also slices of all such types. You may also implement this trait to enable cloning trait objects and custom DSTs (structures containing dynamically-sized fields).

§Safety

Implementations must ensure that when .clone_to_uninit(dst) returns normally rather than panicking, it always leaves *dst initialized as a valid value of type Self.

§See also

  • Clone::clone_from is a safe function which may be used instead when Self is a Sized and the destination is already initialized; it may be able to reuse allocations owned by the destination.
  • ToOwned, which allocates a new destination container.

Required Methods§

source

unsafe fn clone_to_uninit(&self, dst: *mut Self)

🔬This is a nightly-only experimental API. (clone_to_uninit #126799)

Performs copy-assignment from self to dst.

This is analogous to to std::ptr::write(dst, self.clone()), except that self may be a dynamically-sized type (!Sized).

Before this function is called, dst may point to uninitialized memory. After this function is called, dst will point to initialized memory; it will be sound to create a &Self reference from the pointer.

§Safety

Behavior is undefined if any of the following conditions are violated:

  • dst must be valid for writes.
  • dst must be properly aligned.
  • dst must have the same pointer metadata (slice length or dyn vtable) as self.
§Panics

This function may panic. (For example, it might panic if memory allocation for a clone of a value owned by self fails.) If the call panics, then *dst should be treated as uninitialized memory; it must not be read or dropped, because even if it was previously valid, it may have been partially overwritten.

The caller may also need to take care to deallocate the allocation pointed to by dst, if applicable, to avoid a memory leak, and may need to take other precautions to ensure soundness in the presence of unwinding.

Implementors should avoid leaking values by, upon unwinding, dropping all component values that might have already been created. (For example, if a [Foo] of length 3 is being cloned, and the second of the three calls to Foo::clone() unwinds, then the first Foo cloned should be dropped.)

Object Safety§

This trait is not object safe.

Implementors§