Rollup merge of #34911 - frewsxcv:vec-set-len, r=steveklabnik

Rewrite/expand doc examples for `Vec::set_len`.

None

diff --combined src/libcollections/vec.rs
index 518b94b5031b436f8f2372d86a2006fb83cc1af0,9badf8cf1830584abb2b8e405c0beac8850853f6..9ca3a5bd6079ad7a7c020a3520a323d466abf4c6
--- 1/src/libcollections/vec.rs
--- 2/src/libcollections/vec.rs
+++ b/src/libcollections/vec.rs
@@@ -342,18 -342,12 +342,18 @@@ impl<T> Vec<T> 
      ///
      /// * `ptr` needs to have been previously allocated via `String`/`Vec<T>`
      ///   (at least, it's highly likely to be incorrect if it wasn't).
 -    /// * `length` needs to be the length that less than or equal to `capacity`.
 +    /// * `length` needs to be less than or equal to `capacity`.
      /// * `capacity` needs to be the capacity that the pointer was allocated with.
      ///
      /// Violating these may cause problems like corrupting the allocator's
      /// internal datastructures.
      ///
 +    /// The ownership of `ptr` is effectively transferred to the
 +    /// `Vec<T>` which may then deallocate, reallocate or change the
 +    /// contents of memory pointed to by the pointer at will. Ensure
 +    /// that nothing else uses the pointer after calling this
 +    /// function.
 +    ///
      /// # Examples
      ///
      /// ```
@@@ -485,45 -479,18 +485,45 @@@
          }
      }
  
 -    /// Shorten a vector to be `len` elements long, dropping excess elements.
 +    /// Shortens the vector, keeping the first `len` elements and dropping
 +    /// the rest.
      ///
      /// If `len` is greater than the vector's current length, this has no
      /// effect.
      ///
 +    /// The [`drain`] method can emulate `truncate`, but causes the excess
 +    /// elements to be returned instead of dropped.
 +    ///
      /// # Examples
      ///
 +    /// Truncating a five element vector to two elements:
 +    ///
      /// ```
      /// let mut vec = vec![1, 2, 3, 4, 5];
      /// vec.truncate(2);
      /// assert_eq!(vec, [1, 2]);
      /// ```
 +    ///
 +    /// No truncation occurs when `len` is greater than the vector's current
 +    /// length:
 +    ///
 +    /// ```
 +    /// let mut vec = vec![1, 2, 3];
 +    /// vec.truncate(8);
 +    /// assert_eq!(vec, [1, 2, 3]);
 +    /// ```
 +    ///
 +    /// Truncating when `len == 0` is equivalent to calling the [`clear`]
 +    /// method.
 +    ///
 +    /// ```
 +    /// let mut vec = vec![1, 2, 3];
 +    /// vec.truncate(0);
 +    /// assert_eq!(vec, []);
 +    /// ```
 +    ///
 +    /// [`clear`]: #method.clear
 +    /// [`drain`]: #method.drain
      #[stable(feature = "rust1", since = "1.0.0")]
      pub fn truncate(&mut self, len: usize) {
          unsafe {
@@@ -553,7 -520,7 +553,7 @@@
      #[inline]
      #[stable(feature = "vec_as_slice", since = "1.7.0")]
      pub fn as_mut_slice(&mut self) -> &mut [T] {
 -        &mut self[..]
 +        self
      }
  
      /// Sets the length of a vector.
@@@ -565,9 -532,37 +565,37 @@@
      /// # 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]