bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

avoid talking about inverses

Browse source
This commit is contained in:
Ralf Jung 2023-09-21 08:31:16 +02:00
parent 14625f5b3e
commit 6c73f254b9
2 changed files with 14 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

12
library/core/src/ptr/const_ptr.rs
View file

@ -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