1 files changed, 24 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/mem_replace_with_uninit.txt b/src/tools/clippy/src/docs/mem_replace_with_uninit.txt
new file mode 100644
index 000000000..0bb483668
--- /dev/null
+++ b/src/tools/clippy/src/docs/mem_replace_with_uninit.txt
@@ -0,0 +1,24 @@
+### What it does
+Checks for `mem::replace(&mut _, mem::uninitialized())`
+and `mem::replace(&mut _, mem::zeroed())`.
+
+### Why is this bad?
+This will lead to undefined behavior even if the
+value is overwritten later, because the uninitialized value may be
+observed in the case of a panic.
+
+### Example
+```
+use std::mem;
+
+#[allow(deprecated, invalid_value)]
+fn myfunc (v: &mut Vec<i32>) {
+    let taken_v = unsafe { mem::replace(v, mem::uninitialized()) };
+    let new_v = may_panic(taken_v); // undefined behavior on panic
+    mem::forget(mem::replace(v, new_v));
+}
+```
+
+The [take_mut](https://docs.rs/take_mut) crate offers a sound solution,
+at the cost of either lazily creating a replacement value or aborting
+on panic, to ensure that the uninitialized value cannot be observed.
+\ No newline at end of file