take more clarifying text from Gankra's PR

original source: rust-lang#95851
RalfJung · Sep 26, 2023 · 9b7f9c4 · 9b7f9c4
1 parent 6c73f25
commit 9b7f9c4
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 0 deletions.
diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs
@@ -611,6 +611,13 @@ impl<T: ?Sized> *const T {
     /// except that it has a lot more opportunities for UB, in exchange for the compiler
     /// better understanding what you are doing.
     ///
+    /// The primary motivation of this method is for computing the `len` of an array/slice
+    /// of `T` that you are currently representing as a "start" and "end" pointer
+    /// (and "end" is "one past the end" of the array).
+    /// In that case, `end.offset_from(start)` gets you the length of the array.
+    ///
+    /// All of the following safety requirements are trivially satisfied for this usecase.
+    ///
     /// [`offset`]: #method.offset
     ///
     /// # Safety

diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs
@@ -785,6 +785,13 @@ impl<T: ?Sized> *mut T {
     /// except that it has a lot more opportunities for UB, in exchange for the compiler
     /// better understanding what you are doing.
     ///
+    /// The primary motivation of this method is for computing the `len` of an array/slice
+    /// of `T` that you are currently representing as a "start" and "end" pointer
+    /// (and "end" is "one past the end" of the array).
+    /// In that case, `end.offset_from(start)` gets you the length of the array.
+    ///
+    /// All of the following safety requirements are trivially satisfied for this usecase.
+    ///
     /// [`offset`]: pointer#method.offset-1
     ///
     /// # Safety