Add note that Vec::as_mut_ptr() does not materialize a reference to the internal buffer

Author: Manishearth

library/alloc/src/vec/mod.rs

@@ -1218,6 +1218,12 @@ impl<T, A: Allocator> Vec<T, A> {
     /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
     /// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`].
     ///
+    /// This method guarantees that when it is called multiple times without
+    /// the buffer being reallocated in the mean time, the returned pointer will
+    /// always be exactly the same, even for the purpose of the aliasing model, where
+    /// pointers may be invalidated even when the actual memory does not move.
+    /// See the second example below for how this can be used.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1231,6 +1237,16 @@ impl<T, A: Allocator> Vec<T, A> {
     /// }
     /// ```
     ///
+    /// The validity guarantee works out this way:
+    ///
+    /// ```rust
+    /// let mut v = vec![0];
+    /// let ptr = v.as_ptr();
+    /// let x = ptr.read();
+    /// v[0] = 5;
+    /// // Notably, the write above did *not* invalidate `ptr1`:
+    /// let x = ptr.read();
+    /// ```
     /// [`as_mut_ptr`]: Vec::as_mut_ptr
     #[stable(feature = "vec_as_ptr", since = "1.37.0")]
     #[inline]
@@ -1248,6 +1264,13 @@ impl<T, A: Allocator> Vec<T, A> {
     /// Modifying the vector may cause its buffer to be reallocated,
     /// which would also make any pointers to it invalid.
     ///
+    /// This method guarantees that when it is called multiple times without
+    /// the buffer being reallocated in the mean time, the returned pointer will
+    /// always be exactly the same, even for the purpose of the aliasing model, where
+    /// pointers may be invalidated even when the actual memory does not move.
+    /// See the second example below for how this can be used.
+    ///
+    ///
     /// # Examples
     ///
     /// ```
@@ -1265,6 +1288,18 @@ impl<T, A: Allocator> Vec<T, A> {
     /// }
     /// assert_eq!(&*x, &[0, 1, 2, 3]);
     /// ```
+    ///
+    /// The validity guarantee works out this way:
+    ///
+    /// ```rust
+    /// let mut v = vec![0];
+    /// let ptr1 = v.as_mut_ptr();
+    /// ptr1.write(1);
+    /// let ptr2 = v.as_mut_ptr();
+    /// ptr2.write(2);
+    /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
+    /// ptr1.write(3);
+    /// ```
     #[stable(feature = "vec_as_ptr", since = "1.37.0")]
     #[inline]
     pub fn as_mut_ptr(&mut self) -> *mut T {