diff options
| -rw-r--r-- | library/core/src/ptr/const_ptr.rs | 12 | ||||
| -rw-r--r-- | library/core/src/ptr/mut_ptr.rs | 12 |
2 files changed, 14 insertions, 10 deletions
diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs index 0f589647a47..3e68216e40e 100644 --- a/library/core/src/ptr/const_ptr.rs +++ b/library/core/src/ptr/const_ptr.rs @@ -607,8 +607,9 @@ impl<T: ?Sized> *const T { /// Calculates the distance between two pointers. The returned value is in /// units of T: the distance in bytes divided by `mem::size_of::<T>()`. /// - /// This function is the inverse of [`offset`]: it is valid to call and will return - /// `n` if and only if `origin.offset(n)` is valid to call and will return `self`. + /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`, + /// except that it has a lot more opportunities for UB, in exchange for the compiler + /// better understanding what you are doing. /// /// [`offset`]: #method.offset /// @@ -617,7 +618,7 @@ impl<T: ?Sized> *const T { /// If any of the following conditions are violated, the result is Undefined /// Behavior: /// - /// * Both the starting and other pointer must be either in bounds or one + /// * Both `self` and `origin` must be either in bounds or one /// byte past the end of the same [allocated object]. /// /// * Both pointers must be *derived from* a pointer to the same object. @@ -651,8 +652,9 @@ impl<T: ?Sized> *const T { /// needed for `const`-compatibility: the distance between pointers into *different* allocated /// objects is not known at compile-time. However, the requirement also exists at /// runtime and may be exploited by optimizations. If you wish to compute the difference between - /// pointers that are not guaranteed to be from the same allocation, use `(self as - /// usize).sub(origin as usize) / mem::size_of::<T>()`. + /// pointers that are not guaranteed to be from the same allocation, use `(self as isize - + /// origin as isize) / mem::size_of::<T>()`. + // FIXME: recommend `addr()` instead of `as usize` once that is stable. /// /// [`add`]: #method.add /// [allocated object]: crate::ptr#allocated-object diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index d395319b6f3..c89ce52292a 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -781,8 +781,9 @@ impl<T: ?Sized> *mut T { /// Calculates the distance between two pointers. The returned value is in /// units of T: the distance in bytes divided by `mem::size_of::<T>()`. /// - /// This function is the inverse of [`offset`]: it is valid to call and will return - /// `n` if and only if `origin.offset(n)` is valid to call and will return `self`. + /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`, + /// except that it has a lot more opportunities for UB, in exchange for the compiler + /// better understanding what you are doing. /// /// [`offset`]: pointer#method.offset-1 /// @@ -791,7 +792,7 @@ impl<T: ?Sized> *mut T { /// If any of the following conditions are violated, the result is Undefined /// Behavior: /// - /// * Both the starting and other pointer must be either in bounds or one + /// * Both `self` and `origin` must be either in bounds or one /// byte past the end of the same [allocated object]. /// /// * Both pointers must be *derived from* a pointer to the same object. @@ -825,8 +826,9 @@ impl<T: ?Sized> *mut T { /// needed for `const`-compatibility: the distance between pointers into *different* allocated /// objects is not known at compile-time. However, the requirement also exists at /// runtime and may be exploited by optimizations. If you wish to compute the difference between - /// pointers that are not guaranteed to be from the same allocation, use `(self as - /// usize).sub(origin as usize) / mem::size_of::<T>()`. + /// pointers that are not guaranteed to be from the same allocation, use `(self as isize - + /// origin as isize) / mem::size_of::<T>()`. + // FIXME: recommend `addr()` instead of `as usize` once that is stable. /// /// [`add`]: #method.add /// [allocated object]: crate::ptr#allocated-object |