Rollup merge of #34930 - frewsxcv:vec-as-slice, r=steveklabnik

[rust.git] / src / libcollections / vec.rs

diff --git a/src/libcollections/vec.rs b/src/libcollections/vec.rs
index 4cc5b11dc34344b6437435095d710d325d0ce2ce..2d77b38879b8eb8a959f4920b51abbf6bc66f57c 100644 (file)
--- a/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@ -581,9 +581,37 @@ pub fn as_mut_slice(&mut self) -> &mut [T] {
     /// # Examples
     ///
     /// ```
-    /// let mut v = vec![1, 2, 3, 4];
+    /// use std::ptr;
+    ///
+    /// let mut vec = vec!['r', 'u', 's', 't'];
+    ///
+    /// unsafe {
+    ///     ptr::drop_in_place(&mut vec[3]);
+    ///     vec.set_len(3);
+    /// }
+    /// assert_eq!(vec, ['r', 'u', 's']);
+    /// ```
+    ///
+    /// In this example, there is a memory leak since the memory locations
+    /// owned by the vector were not freed prior to the `set_len` call:
+    ///
+    /// ```
+    /// let mut vec = vec!['r', 'u', 's', 't'];
+    ///
+    /// unsafe {
+    ///     vec.set_len(0);
+    /// }
+    /// ```
+    ///
+    /// In this example, the vector gets expanded from zero to four items
+    /// without any memory allocations occurring, resulting in vector
+    /// values of unallocated memory:
+    ///
+    /// ```
+    /// let mut vec: Vec<char> = Vec::new();
+    ///
     /// unsafe {
-    ///     v.set_len(1);
+    ///     vec.set_len(4);
     /// }
     /// ```
     #[inline]