`std::ptr::write` docs don't mention that `src` is leaked

[niconii]

EDIT: To summarize it a bit better, since it seems like I worded things a bit unclearly:

src's destructor doesn't get run when it's passed by-value to ptr::write, but the docs don't really make this clear. It would be better to clarify this, especially given it's an unsafe function.

---

#[derive(Debug)]
struct Foo(i32);

impl Drop for Foo {
 fn drop(&mut self) {
 println!("{:?} dropped!", self);
 }
}

fn main() {
 let mut dst = Foo(0);
 let src = Foo(1);
 
 unsafe { std::ptr::write(&mut dst, src); }
 
 println!("dst = {:?}", dst);
}

This code prints:

dst = Foo(1)
Foo(1) dropped!

demonstrating that the original value stored in dst, and the value passed to std::ptr::write, were not dropped; only dst was dropped after the println! line.

However, the docs for std::ptr::write only mention that the former isn't dropped, saying nothing about the latter.

[sfackler]

The initial value of dst wasn't dropped - that would print Foo(0) dropped!.

[niconii]

@sfackler Yes, and I said as much. That's not the problem.

The problem is that although the docs mention that dst's original value isn't dropped, the docs say nothing about whether the value passed as src is dropped or not, and it isn't.

[sfackler]

src is moved by value into the write function - it no longer exists to drop after the call. It behaves like any other function (e.g. Vec::push) in that regard.

[niconii]

What I'm saying is that ptr::write leaks its src argument, but this is not documented.

I opened this issue because someone in #rust-beginners was confused about this. They weren't sure whether it was safe to write a Box<T> into a *mut Box<T> with this function, or if the Box<T> would be dropped when passed in by-value.

[durka]

I agree with @sfackler that it doesn't make sense to describe this as a "leak" because the value that gets moved from src into dst is dropped, later. I think we should change the doc to emphasize that src is moved.

[niconii]

Yes, that would work. Right now the docs don't make it clear enough that src's destructor doesn't get run when it's passed to ptr::write.