docs: Mention spare_capacity_mut() in Vec::set_len

library/alloc/src/vec/mod.rs

@@ -1460,6 +1460,20 @@ impl<T, A: Allocator> Vec<T, A> {
     /// # }
     /// ```
     ///
+    /// It is possible to initialize the spare capacity with [`spare_capacity_mut()`]:
+    ///
+    /// ```
+    /// let mut vec: Vec<u8> = Vec::with_capacity(1024);
+    /// let remaining = vec.spare_capacity_mut();
+    /// remaining[..512].iter_mut().for_each(|x| *x = MaybeUninit::new(0));
+    /// // SAFETY:
+    /// // 1. The `new_len` is less than the `capacity`.
+    /// // 2. The elements in range `0..new_len` are initialized.
+    /// unsafe {
+    ///     vec.set_len(256);
+    /// }
+    /// ```
+    ///
     /// While the following example is sound, there is a memory leak since
     /// the inner vectors were not freed prior to the `set_len` call:
     ///
@@ -1477,6 +1491,8 @@ impl<T, A: Allocator> Vec<T, A> {
     ///
     /// Normally, here, one would use [`clear`] instead to correctly drop
     /// the contents and thus not leak memory.
+    ///
+    /// [`spare_capacity_mut()`]: Vec::spare_capacity_mut
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub unsafe fn set_len(&mut self, new_len: usize) {