Rollup merge of #129892 - oskgo:clarify-slice-from-raw, r=RalfJung

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

1 files changed, 8 insertions, 8 deletions

diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs
index 85507eb8a73..2cf3fecb475 100644
--- a/library/core/src/slice/raw.rs
+++ b/library/core/src/slice/raw.rs
@@ -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`
@@ -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`
@@ -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*
@@ -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.
@@ -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*
@@ -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.