Rollup merge of rust-lang#68054 - tspiteri:null-unchecked-as_mut, r=c…

…ramertj

doc: add Null-unchecked version section to mut pointer as_mut method

The [`as_ref`](https://doc.rust-lang.org/std/primitive.pointer.html#method.as_ref-1) method already has a *Null-unchecked version* section, its example is a modification of the example in the main `as_ref` section. Similarly the example in this PR is a modification of the example in main [`as_mut`](https://doc.rust-lang.org/std/primitive.pointer.html#method.as_mut) section.

Fixes rust-lang#68032.

src/libcore/ptr/mut_ptr.rs

@@ -250,6 +250,20 @@ impl<T: ?Sized> *mut T {
     /// *first_value = 4;
     /// println!("{:?}", s); // It'll print: "[4, 2, 3]".
     /// ```
+    ///
+    /// # Null-unchecked version
+    ///
+    /// If you are sure the pointer can never be null and are looking for some kind of
+    /// `as_mut_unchecked` that returns the `&mut T` instead of `Option<&mut T>`, know that
+    /// you can dereference the pointer directly.
+    ///
+    /// ```
+    /// let mut s = [1, 2, 3];
+    /// let ptr: *mut u32 = s.as_mut_ptr();
+    /// let first_value = unsafe { &mut *ptr };
+    /// *first_value = 4;
+    /// println!("{:?}", s); // It'll print: "[4, 2, 3]".
+    /// ```
     #[stable(feature = "ptr_as_ref", since = "1.9.0")]
     #[inline]
     pub unsafe fn as_mut<'a>(self) -> Option<&'a mut T> {