/// * 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 2<sup>63</sup> 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
///
/// * 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 2<sup>63</sup> 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
///