mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-22 06:44:35 +00:00
also remove redundant requirements from offset()
This commit is contained in:
parent
273d253ce6
commit
9ba492f279
@ -390,37 +390,26 @@ impl<T: ?Sized> *const T {
|
||||
if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit<T>) }) }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer.
|
||||
/// Adds an offset to a pointer.
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_offset`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
@ -622,7 +611,7 @@ impl<T: ?Sized> *const T {
|
||||
/// * The distance between the pointers, in bytes, must be an exact multiple
|
||||
/// of the size of `T`.
|
||||
///
|
||||
/// As a consequence, the absolute distance between the pointers, **in bytes**, computed on
|
||||
/// As a consequence, the absolute distance between the pointers, in bytes, computed on
|
||||
/// mathematical integers (without "wrapping around"), cannot overflow an `isize`. This is
|
||||
/// implied by the in-bounds requirement, and the fact that no allocated object can be larger
|
||||
/// than `isize::MAX` bytes.
|
||||
@ -862,37 +851,26 @@ impl<T: ?Sized> *const T {
|
||||
}
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
|
||||
/// Adds an offset to a pointer (convenience for `.offset(count as isize)`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a `usize`.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_add`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
@ -946,7 +924,7 @@ impl<T: ?Sized> *const T {
|
||||
unsafe { self.cast::<u8>().add(count).with_metadata_of(self) }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for
|
||||
/// Subtracts an offset from a pointer (convenience for
|
||||
/// `.offset((count as isize).wrapping_neg())`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
@ -954,30 +932,19 @@ impl<T: ?Sized> *const T {
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset cannot exceed `isize::MAX` **bytes**.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_sub`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
|
@ -404,37 +404,26 @@ impl<T: ?Sized> *mut T {
|
||||
if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit<T>) }) }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer.
|
||||
/// Adds an offset to a pointer.
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_offset`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
@ -1003,37 +992,26 @@ impl<T: ?Sized> *mut T {
|
||||
unsafe { (self as *const T).sub_ptr(origin) }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
|
||||
/// Adds an offset to a pointer (convenience for `.offset(count as isize)`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a `usize`.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_add`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
@ -1087,7 +1065,7 @@ impl<T: ?Sized> *mut T {
|
||||
unsafe { self.cast::<u8>().add(count).with_metadata_of(self) }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for
|
||||
/// Subtracts an offset from a pointer (convenience for
|
||||
/// `.offset((count as isize).wrapping_neg())`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
@ -1095,30 +1073,19 @@ impl<T: ?Sized> *mut T {
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting
|
||||
/// pointer must be either in bounds or at the end of the same [allocated object].
|
||||
/// (If it is zero, then the function is always well-defined.)
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset cannot exceed `isize::MAX` **bytes**.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// Consider using [`wrapping_sub`] instead if these constraints are
|
||||
/// difficult to satisfy. The only advantage of this method is that it
|
||||
|
@ -476,36 +476,26 @@ impl<T: ?Sized> NonNull<T> {
|
||||
unsafe { NonNull { pointer: self.as_ptr() as *mut U } }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer.
|
||||
/// Adds an offset to a pointer.
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * Both the starting and resulting pointer must be either in bounds or one
|
||||
/// byte past the end of the same [allocated object].
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// [allocated object]: crate::ptr#allocated-object
|
||||
///
|
||||
@ -562,36 +552,26 @@ impl<T: ?Sized> NonNull<T> {
|
||||
unsafe { NonNull { pointer: self.pointer.byte_offset(count) } }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
|
||||
/// Adds an offset to a pointer (convenience for `.offset(count as isize)`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
/// offset of `3 * size_of::<T>()` bytes.
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * Both the starting and resulting pointer must be either in bounds or one
|
||||
/// byte past the end of the same [allocated object].
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a `usize`.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// [allocated object]: crate::ptr#allocated-object
|
||||
///
|
||||
@ -649,7 +629,7 @@ impl<T: ?Sized> NonNull<T> {
|
||||
unsafe { NonNull { pointer: self.pointer.byte_add(count) } }
|
||||
}
|
||||
|
||||
/// Calculates the offset from a pointer (convenience for
|
||||
/// Subtracts an offset from a pointer (convenience for
|
||||
/// `.offset((count as isize).wrapping_neg())`).
|
||||
///
|
||||
/// `count` is in units of T; e.g., a `count` of 3 represents a pointer
|
||||
@ -657,29 +637,19 @@ impl<T: ?Sized> NonNull<T> {
|
||||
///
|
||||
/// # Safety
|
||||
///
|
||||
/// If any of the following conditions are violated, the result is Undefined
|
||||
/// Behavior:
|
||||
/// If any of the following conditions are violated, the result is Undefined Behavior:
|
||||
///
|
||||
/// * Both the starting and resulting pointer must be either in bounds or one
|
||||
/// byte past the end of the same [allocated object].
|
||||
/// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
|
||||
///
|
||||
/// * The computed offset cannot exceed `isize::MAX` **bytes**.
|
||||
/// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
|
||||
/// [allocated object], and the entire memory range between `self` and the result must be in
|
||||
/// bounds of that allocated object. In particular, this range must not "wrap around" the edge
|
||||
/// of the address space.
|
||||
///
|
||||
/// * The offset being in bounds cannot rely on "wrapping around" the address
|
||||
/// space. That is, the infinite-precision sum must fit in a usize.
|
||||
///
|
||||
/// The compiler and standard library generally tries 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
|
||||
/// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe.
|
||||
///
|
||||
/// Most platforms fundamentally can't even construct such an 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.
|
||||
/// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
|
||||
/// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
|
||||
/// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
|
||||
/// safe.
|
||||
///
|
||||
/// [allocated object]: crate::ptr#allocated-object
|
||||
///
|
||||
|
Loading…
Reference in New Issue
Block a user