clarify 'remains attached', and remove recommendation to use integer arithmetic

Author: RalfJung

core/src/ptr/const_ptr.rs

@@ -245,8 +245,8 @@ impl<T: ?Sized> *const T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -264,9 +264,6 @@ impl<T: ?Sized> *const T {
     /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other
     /// words, leaving the allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`offset`]: #method.offset
     /// [allocated object]: crate::ptr#allocated-object
     ///
@@ -594,8 +591,8 @@ impl<T: ?Sized> *const T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -613,9 +610,6 @@ impl<T: ?Sized> *const T {
     /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
     /// allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`add`]: #method.add
     /// [allocated object]: crate::ptr#allocated-object
     ///
@@ -659,8 +653,8 @@ impl<T: ?Sized> *const T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -678,9 +672,6 @@ impl<T: ?Sized> *const T {
     /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
     /// allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`sub`]: #method.sub
     /// [allocated object]: crate::ptr#allocated-object
     ///

core/src/ptr/mut_ptr.rs

@@ -251,8 +251,8 @@ impl<T: ?Sized> *mut T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -270,9 +270,6 @@ impl<T: ?Sized> *mut T {
     /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other
     /// words, leaving the allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`offset`]: #method.offset
     /// [allocated object]: crate::ptr#allocated-object
     ///
@@ -700,8 +697,8 @@ impl<T: ?Sized> *mut T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -719,9 +716,6 @@ impl<T: ?Sized> *mut T {
     /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
     /// allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`add`]: #method.add
     /// [allocated object]: crate::ptr#allocated-object
     ///
@@ -765,8 +759,8 @@ impl<T: ?Sized> *mut T {
     ///
     /// This operation itself is always safe, but using the resulting pointer is not.
     ///
-    /// The resulting pointer remains attached to the same [allocated object] that `self` points to.
-    /// It may *not* be used to access a different allocated object.
+    /// The resulting pointer "remembers" the [allocated object] that `self` points to; it may not
+    /// be used to read or write other allocated objects.
     ///
     /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z`
     /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
@@ -784,9 +778,6 @@ impl<T: ?Sized> *mut T {
     /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
     /// allocated object and then re-entering it later is permitted.
     ///
-    /// If you need to cross object boundaries, cast the pointer to an integer and
-    /// do the arithmetic there.
-    ///
     /// [`sub`]: #method.sub
     /// [allocated object]: crate::ptr#allocated-object
     ///