Skip to content

Commit

Permalink
Rollup merge of #129892 - oskgo:clarify-slice-from-raw, r=RalfJung
Browse files Browse the repository at this point in the history
Clarify language around ptrs in slice::raw

More specifically we explicitly mention that the pointer should be non-null as a top level requirement. Nullptrs are always valid for zero sized operations, so just validity (and alignment) does not guarantee non-nullness as implied in the existing docs.

We also explicitly call out ZSTs as an additional example where perhaps unintuitively alignment and non-nullness still have to hold.

Finally we change `data` in the range functions to `start`, which seems like a typo to me.

Touches docs for #89792

r? RalfJung
  • Loading branch information
matthiaskrgr authored Sep 2, 2024
2 parents 19a6bf3 + 7494224 commit 718b124
Showing 1 changed file with 8 additions and 8 deletions.
16 changes: 8 additions & 8 deletions library/core/src/slice/raw.rs
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ use crate::{array, ptr, ub_checks};
///
/// Behavior is undefined if any of the following conditions are violated:
///
/// * `data` must be [valid] for reads for `len * mem::size_of::<T>()` many bytes,
/// * `data` must be non-null, [valid] for reads for `len * mem::size_of::<T>()` many bytes,
/// and it must be properly aligned. This means in particular:
///
/// * The entire memory range of this slice must be contained within a single allocated object!
/// Slices can never span across multiple allocated objects. See [below](#incorrect-usage)
/// for an example incorrectly not taking this into account.
/// * `data` must be non-null and aligned even for zero-length slices. One
/// * `data` must be non-null and aligned even for zero-length slices or slices of ZSTs. One
/// reason for this is that enum layout optimizations may rely on references
/// (including slices of any length) being aligned and non-null to distinguish
/// them from other data. You can obtain a pointer that is usable as `data`
Expand Down Expand Up @@ -146,12 +146,12 @@ pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T]
///
/// Behavior is undefined if any of the following conditions are violated:
///
/// * `data` must be [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
/// * `data` must be non-null, [valid] for both reads and writes for `len * mem::size_of::<T>()` many bytes,
/// and it must be properly aligned. This means in particular:
///
/// * The entire memory range of this slice must be contained within a single allocated object!
/// Slices can never span across multiple allocated objects.
/// * `data` must be non-null and aligned even for zero-length slices. One
/// * `data` must be non-null and aligned even for zero-length slices or slices of ZSTs. One
/// reason for this is that enum layout optimizations may rely on references
/// (including slices of any length) being aligned and non-null to distinguish
/// them from other data. You can obtain a pointer that is usable as `data`
Expand Down Expand Up @@ -219,7 +219,7 @@ pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
///
/// Behavior is undefined if any of the following conditions are violated:
///
/// * The `start` pointer of the range must be a [valid] and properly aligned pointer
/// * The `start` pointer of the range must be a non-null, [valid] and properly aligned pointer
/// to the first element of a slice.
///
/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
Expand All @@ -235,7 +235,7 @@ pub const fn from_mut<T>(s: &mut T) -> &mut [T] {
/// of lifetime `'a`, except inside an `UnsafeCell`.
///
/// * The total length of the range must be no larger than `isize::MAX`,
/// and adding that size to `data` must not "wrap around" the address space.
/// and adding that size to `start` must not "wrap around" the address space.
/// See the safety documentation of [`pointer::offset`].
///
/// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements.
Expand Down Expand Up @@ -288,7 +288,7 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
///
/// Behavior is undefined if any of the following conditions are violated:
///
/// * The `start` pointer of the range must be a [valid] and properly aligned pointer
/// * The `start` pointer of the range must be a non-null, [valid] and properly aligned pointer
/// to the first element of a slice.
///
/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past*
Expand All @@ -305,7 +305,7 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] {
/// Both read and write accesses are forbidden.
///
/// * The total length of the range must be no larger than `isize::MAX`,
/// and adding that size to `data` must not "wrap around" the address space.
/// and adding that size to `start` must not "wrap around" the address space.
/// See the safety documentation of [`pointer::offset`].
///
/// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements.
Expand Down

0 comments on commit 718b124

Please sign in to comment.