mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

offset_from: docs improvements

Browse Source
This commit is contained in:
Ralf Jung 2023-07-17 17:45:31 +02:00
parent 4f226925ce
commit 62bdb1a6e0
2 changed files with 20 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -607,7 +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`].
/// 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<T: ?Sized> *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::<T>()` to avoid this requirement.
///
/// [`add`]: #method.add
/// [allocated object]: crate::ptr#allocated-object
///
@ -703,7 +711,7 @@ impl<T: ?Sized> *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,

12
library/core/src/ptr/mut_ptr.rs
View File

@ -781,7 +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`].
/// 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<T: ?Sized> *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::<T>()` to avoid this requirement.
///
/// [`add`]: #method.add
/// [allocated object]: crate::ptr#allocated-object
///
@ -875,7 +883,7 @@ impl<T: ?Sized> *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,