From ebe0407dbf1e0e2135ca75c47d525f6217959eba Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Thu, 4 Mar 2021 09:46:56 +0100 Subject: [PATCH] improve offset_from docs --- library/core/src/ptr/const_ptr.rs | 20 +++++++++++++------- library/core/src/ptr/mut_ptr.rs | 20 +++++++++++++------- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs index cfc1bfd54be2d..62ca07fc5a4e2 100644 --- a/library/core/src/ptr/const_ptr.rs +++ b/library/core/src/ptr/const_ptr.rs @@ -320,25 +320,31 @@ impl *const T { /// * Both pointers must be *derived from* a pointer to the same object. /// (See below for an example.) /// - /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. - /// /// * The distance between the pointers, in bytes, must be an exact multiple /// of the size of `T`. /// + /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. + /// /// * The distance being in bounds cannot rely on "wrapping around" the address space. /// - /// The compiler and standard library generally try to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `ptr_into_vec.offset_from(vec.as_ptr())` is always safe. + /// Rust types are never larger than `isize::MAX` and Rust allocations never wrap around the + /// address space, so two pointers within some value of any Rust type `T` will always satisfy + /// the last two conditions. The standard library also generally ensures that allocations + /// never reach a size where an offset is a concern. For instance, `Vec` and `Box` ensure they + /// never allocate more than `isize::MAX` bytes, so `ptr_into_vec.offset_from(vec.as_ptr())` + /// always satisfies the last two conditions. /// - /// Most platforms fundamentally can't even construct such an allocation. + /// Most platforms fundamentally can't even construct such a large allocation. /// For instance, no known 64-bit platform can ever serve a request /// for 263 bytes due to page-table limitations or splitting the address space. /// However, some 32-bit and 16-bit platforms may successfully serve a request for /// more than `isize::MAX` bytes with things like Physical Address /// Extension. As such, memory acquired directly from allocators or memory /// mapped files *may* be too large to handle with this function. + /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on + /// such large allocations either.) + /// + /// [`add`]: #method.add /// /// # Panics /// diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index 06bacc8635147..a365b66d8fcf4 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -491,25 +491,31 @@ impl *mut T { /// * Both pointers must be *derived from* a pointer to the same object. /// (See below for an example.) /// - /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. - /// /// * The distance between the pointers, in bytes, must be an exact multiple /// of the size of `T`. /// + /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. + /// /// * The distance being in bounds cannot rely on "wrapping around" the address space. /// - /// The compiler and standard library generally try to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `ptr_into_vec.offset_from(vec.as_ptr())` is always safe. + /// Rust types are never larger than `isize::MAX` and Rust allocations never wrap around the + /// address space, so two pointers within some value of any Rust type `T` will always satisfy + /// the last two conditions. The standard library also generally ensures that allocations + /// never reach a size where an offset is a concern. For instance, `Vec` and `Box` ensure they + /// never allocate more than `isize::MAX` bytes, so `ptr_into_vec.offset_from(vec.as_ptr())` + /// always satisfies the last two conditions. /// - /// Most platforms fundamentally can't even construct such an allocation. + /// Most platforms fundamentally can't even construct such a large allocation. /// For instance, no known 64-bit platform can ever serve a request /// for 263 bytes due to page-table limitations or splitting the address space. /// However, some 32-bit and 16-bit platforms may successfully serve a request for /// more than `isize::MAX` bytes with things like Physical Address /// Extension. As such, memory acquired directly from allocators or memory /// mapped files *may* be too large to handle with this function. + /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on + /// such large allocations either.) + /// + /// [`add`]: #method.add /// /// # Panics ///