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 /// Calculates the distance between two pointers. The returned value is in
/// units of T: the distance in bytes divided by `mem::size_of::<T>()`. /// 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 /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
/// `n` if and only if `origin.offset(n)` is valid to call and will return `self`. /// except that it has a lot more opportunities for UB, in exchange for the compiler
/// better understanding what you are doing.
/// ///
/// [`offset`]: #method.offset /// [`offset`]: #method.offset
/// ///
@ -617,7 +618,7 @@ impl<T: ?Sized> *const T {
/// If any of the following conditions are violated, the result is Undefined /// If any of the following conditions are violated, the result is Undefined
/// Behavior: /// 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]. /// byte past the end of the same [allocated object].
/// ///
/// * Both pointers must be *derived from* a pointer to the same 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 /// needed for `const`-compatibility: the distance between pointers into *different* allocated
/// objects is not known at compile-time. However, the requirement also exists at /// 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 /// 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 /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
/// usize).sub(origin as usize) / mem::size_of::<T>()`. /// origin as isize) / mem::size_of::<T>()`.
// FIXME: recommend `addr()` instead of `as usize` once that is stable.
/// ///
/// [`add`]: #method.add /// [`add`]: #method.add
/// [allocated object]: crate::ptr#allocated-object /// [allocated object]: crate::ptr#allocated-object

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

@ -781,8 +781,9 @@ impl<T: ?Sized> *mut T {
/// Calculates the distance between two pointers. The returned value is in /// Calculates the distance between two pointers. The returned value is in
/// units of T: the distance in bytes divided by `mem::size_of::<T>()`. /// 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 /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
/// `n` if and only if `origin.offset(n)` is valid to call and will return `self`. /// 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 /// [`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 /// If any of the following conditions are violated, the result is Undefined
/// Behavior: /// 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]. /// byte past the end of the same [allocated object].
/// ///
/// * Both pointers must be *derived from* a pointer to the same 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 /// needed for `const`-compatibility: the distance between pointers into *different* allocated
/// objects is not known at compile-time. However, the requirement also exists at /// 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 /// 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 /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
/// usize).sub(origin as usize) / mem::size_of::<T>()`. /// origin as isize) / mem::size_of::<T>()`.
// FIXME: recommend `addr()` instead of `as usize` once that is stable.
/// ///
/// [`add`]: #method.add /// [`add`]: #method.add
/// [allocated object]: crate::ptr#allocated-object /// [allocated object]: crate::ptr#allocated-object