offset_from / sub_ptr docs: emphasize that pointers must be in the same allocation

Author: RalfJung

library/core/src/ptr/const_ptr.rs

@@ -582,7 +582,7 @@ impl<T: ?Sized> *const T {
  intrinsics::ptr_mask(self.cast::<()>(), mask).with_metadata_of(self)
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
 ///
 /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
@@ -677,7 +677,7 @@ impl<T: ?Sized> *const T {
 unsafe{ intrinsics::ptr_offset_from(self, origin)}
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of **bytes**.
 ///
 /// This is purely a convenience for casting to a `u8` pointer and
@@ -695,7 +695,7 @@ impl<T: ?Sized> *const T {
 unsafe{self.cast::<u8>().offset_from(origin.cast::<u8>())}
 }
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 ///
@@ -790,7 +790,7 @@ impl<T: ?Sized> *const T {
 unsafe{ intrinsics::ptr_offset_from_unsigned(self, origin)}
 }
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of **bytes**.
 ///

library/core/src/ptr/mut_ptr.rs

@@ -746,7 +746,7 @@ impl<T: ?Sized> *mut T {
 (selfas*constT).guaranteed_ne(other as_)
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
 ///
 /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
@@ -839,7 +839,7 @@ impl<T: ?Sized> *mut T {
 unsafe{(selfas*constT).offset_from(origin)}
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of **bytes**.
 ///
 /// This is purely a convenience for casting to a `u8` pointer and
@@ -857,7 +857,7 @@ impl<T: ?Sized> *mut T {
 unsafe{self.cast::<u8>().offset_from(origin.cast::<u8>())}
 }
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 ///
@@ -930,7 +930,7 @@ impl<T: ?Sized> *mut T {
 unsafe{(selfas*constT).sub_ptr(origin)}
 }
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of **bytes**.
 ///

library/core/src/ptr/non_null.rs

@@ -676,7 +676,7 @@ impl<T: ?Sized> NonNull<T> {
 unsafe{NonNull{pointer:self.pointer.byte_sub(count)}}
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
 ///
 /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
@@ -773,7 +773,7 @@ impl<T: ?Sized> NonNull<T> {
 unsafe{self.pointer.offset_from(origin.pointer)}
 }
 
-/// Calculates the distance between two pointers. The returned value is in
+/// Calculates the distance between two pointers within the same allocation. The returned value is in
 /// units of **bytes**.
 ///
 /// This is purely a convenience for casting to a `u8` pointer and
@@ -793,7 +793,7 @@ impl<T: ?Sized> NonNull<T> {
 
 // N.B. `wrapping_offset``, `wrapping_add`, etc are not implemented because they can wrap to null
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 ///
@@ -866,7 +866,7 @@ impl<T: ?Sized> NonNull<T> {
 unsafe{self.pointer.sub_ptr(subtracted.pointer)}
 }
 
-/// Calculates the distance between two pointers, *where it's known that
+/// Calculates the distance between two pointers within the same allocation, *where it's known that
 /// `self` is equal to or greater than `origin`*. The returned value is in
 /// units of **bytes**.
 ///