From e36f59e1a2a5d94512b5fb66a0e4e224cd15c092 Mon Sep 17 00:00:00 2001 From: Henri Sivonen Date: Fri, 28 Apr 2017 12:25:02 +0300 Subject: [PATCH] Explain why zero-length slices require a non-null pointer --- src/libcore/slice/mod.rs | 8 ++++++-- src/libcore/str/mod.rs | 5 ++++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs index 87dfdfe57b6..9e3bd911546 100644 --- a/src/libcore/slice/mod.rs +++ b/src/libcore/slice/mod.rs @@ -2354,7 +2354,10 @@ impl<'a, T> FusedIterator for ChunksMut<'a, T> {} /// valid for `len` elements, nor whether the lifetime inferred is a suitable /// lifetime for the returned slice. /// -/// `p` must be non-null, even for zero-length slices. +/// `p` must be non-null, even for zero-length slices, because non-zero bits +/// are required to distinguish between a zero-length slice within `Some()` +/// from `None`. `p` can be a bogus non-dereferencable pointer, such as `0x1`, +/// for zero-length slices, though. /// /// # Caveat /// @@ -2387,7 +2390,8 @@ pub unsafe fn from_raw_parts<'a, T>(p: *const T, len: usize) -> &'a [T] { /// /// This function is unsafe for the same reasons as `from_raw_parts`, as well /// as not being able to provide a non-aliasing guarantee of the returned -/// mutable slice. +/// mutable slice. `p` must be non-null even for zero-length slices as with +/// `from_raw_parts`. #[inline] #[stable(feature = "rust1", since = "1.0.0")] pub unsafe fn from_raw_parts_mut<'a, T>(p: *mut T, len: usize) -> &'a mut [T] { diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 2ceef54ffed..6b627430904 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -319,7 +319,10 @@ pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> { /// /// The data must be valid UTF-8 /// -/// `p` must be non-null, even for zero-length str. +/// `p` must be non-null, even for zero-length strs, because non-zero bits +/// are required to distinguish between a zero-length str within `Some()` +/// from `None`. `p` can be a bogus non-dereferencable pointer, such as `0x1`, +/// for zero-length strs, though. /// /// # Caveat ///