From bc1216e0464c5bf44158b8cb5319ff70446b5a13 Mon Sep 17 00:00:00 2001 From: Maybe Waffle Date: Mon, 3 Oct 2022 00:41:54 +0000 Subject: [PATCH 1/2] Document when `slice::from_ptr_range[_mut]` panic --- library/core/src/slice/raw.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs index f1e8bc79bf4a2..50340a92d0d87 100644 --- a/library/core/src/slice/raw.rs +++ b/library/core/src/slice/raw.rs @@ -188,6 +188,10 @@ pub const fn from_mut(s: &mut T) -> &mut [T] { /// /// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements. /// +/// # Panics +/// +/// This function panics if `T` is a Zero-Sized Type (“ZST”). +/// /// # Caveat /// /// The lifetime for the returned slice is inferred from its usage. To @@ -247,6 +251,10 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] { /// /// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements. /// +/// # Panics +/// +/// This function panics if `T` is a Zero-Sized Type (“ZST”). +/// /// # Examples /// /// ``` From 2cd5fafd2597e4d2561bcfe54afb5a9f16b72cc5 Mon Sep 17 00:00:00 2001 From: Maybe Waffle Date: Mon, 3 Oct 2022 00:44:50 +0000 Subject: [PATCH 2/2] Sync docs of `slice::{from_ptr_range, from_ptr_range_mut}` --- library/core/src/slice/raw.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs index 50340a92d0d87..3c5abd215a4b7 100644 --- a/library/core/src/slice/raw.rs +++ b/library/core/src/slice/raw.rs @@ -223,9 +223,15 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] { unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) } } -/// Performs the same functionality as [`from_ptr_range`], except that a +/// Forms a mutable slice from a pointer range. +/// +/// This is the same functionality as [`from_ptr_range`], except that a /// mutable slice is returned. /// +/// This function is useful for interacting with foreign interfaces which +/// use two pointers to refer to a range of elements in memory, as is +/// common in C++. +/// /// # Safety /// /// Behavior is undefined if any of the following conditions are violated: @@ -255,6 +261,14 @@ pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] { /// /// This function panics if `T` is a Zero-Sized Type (“ZST”). /// +/// # Caveat +/// +/// The lifetime for the returned slice is inferred from its usage. To +/// prevent accidental misuse, it's suggested to tie the lifetime to whichever +/// source lifetime is safe in the context, such as by providing a helper +/// function taking the lifetime of a host value for the slice, or by explicit +/// annotation. +/// /// # Examples /// /// ```