From 62bdb1a6e0011d6dbbcc552afebaffbd8fd26104 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Mon, 17 Jul 2023 17:45:31 +0200 Subject: [PATCH] offset_from: docs improvements --- library/core/src/ptr/const_ptr.rs | 12 ++++++++++-- library/core/src/ptr/mut_ptr.rs | 12 ++++++++++-- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs index ee69d89a4b7..b89e9e260e7 100644 --- a/library/core/src/ptr/const_ptr.rs +++ b/library/core/src/ptr/const_ptr.rs @@ -607,7 +607,9 @@ impl *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::()`. /// - /// This function is the inverse of [`offset`]. + /// This function is the inverse of [`offset`]: it is valid to call if and only if + /// `self` could have been computed as `origin.offset(n)` for some `n`, and it will + /// then return that `n`. /// /// [`offset`]: #method.offset /// @@ -646,6 +648,12 @@ impl *const T { /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on /// such large allocations either.) /// + /// The requirement for pointers to be derived from the same allocated object is primarily + /// needed for `const`-compatibility: at compile-time, pointers into *different* allocated + /// object do not have a known distance to each other. However, the requirement also exists at + /// runtime, and may be exploited by optimizations. You can use `(self as usize).sub(origin as + /// usize) / mem::size_of::()` to avoid this requirement. + /// /// [`add`]: #method.add /// [allocated object]: crate::ptr#allocated-object /// @@ -703,7 +711,7 @@ impl *const T { /// units of **bytes**. /// /// This is purely a convenience for casting to a `u8` pointer and - /// using [offset_from][pointer::offset_from] on it. See that method for + /// using [`offset_from`][pointer::offset_from] on it. See that method for /// documentation and safety requirements. /// /// For non-`Sized` pointees this operation considers only the data pointers, diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index 6d623b82c1c..e7611c90344 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -781,7 +781,9 @@ impl *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::()`. /// - /// This function is the inverse of [`offset`]. + /// This function is the inverse of [`offset`]: it is valid to call if and only if + /// `self` could have been computed as `origin.offset(n)` for some `n`, and it will + /// then return that `n`. /// /// [`offset`]: pointer#method.offset-1 /// @@ -820,6 +822,12 @@ impl *mut T { /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on /// such large allocations either.) /// + /// The requirement for pointers to be derived from the same allocated object is primarily + /// needed for `const`-compatibility: at compile-time, pointers into *different* allocated + /// object do not have a known distance to each other. However, the requirement also exists at + /// runtime, and may be exploited by optimizations. You can use `(self as usize).sub(origin as + /// usize) / mem::size_of::()` to avoid this requirement. + /// /// [`add`]: #method.add /// [allocated object]: crate::ptr#allocated-object /// @@ -875,7 +883,7 @@ impl *mut T { /// units of **bytes**. /// /// This is purely a convenience for casting to a `u8` pointer and - /// using [offset_from][pointer::offset_from] on it. See that method for + /// using [`offset_from`][pointer::offset_from] on it. See that method for /// documentation and safety requirements. /// /// For non-`Sized` pointees this operation considers only the data pointers,