From c3f48f206c13b6c307b6f49679c2f2e50e35ed17 Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Tue, 31 Oct 2023 18:24:13 -0700 Subject: [PATCH 1/4] [slice] Document slice DSTs, including size guarantees Makes progress on https://github.com/rust-lang/unsafe-code-guidelines/issues/465 --- library/core/src/primitive_docs.rs | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index f3695d16d7a6b..8524177149f6c 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -868,6 +868,33 @@ mod prim_array {} /// * Further methods that return iterators are [`.split`], [`.splitn`], /// [`.chunks`], [`.windows`] and more. /// +/// ## Use in slice-based dynamically-sized types +/// +/// Slices can be used to construct "slice-based dynamically-sized types", also +/// known as "slice DSTs" or "custom DSTs": +/// +/// ```rust +/// struct SliceDst { +/// a: u8, +/// b: u16, +/// c: [u32], +/// } +/// ``` +/// +/// Just like a slice, a slice DST is a `!Sized` type, and cannot be used by-value. +/// References to slice DSTs encode the number of elements in the trailing slice +/// field: +/// +/// ```rust +/// # struct SliceDst { a: u8, b: u16, c: [u32] } +/// let pointer_size = std::mem::size_of::<&u8>(); +/// assert_eq!(2 * pointer_size, std::mem::size_of::<&SliceDst>()); +/// ``` +/// +/// Rust guarantees that, if a slice DST compiles successfully, then the instance +/// of that type with 0 elements in its trailing slice is no more than `isize::MAX` +/// bytes in size. +/// /// [`Hash`]: core::hash::Hash /// [`.iter`]: slice::iter /// [`.iter_mut`]: slice::iter_mut From 49eecf249f3b4981d22db5205f814deefcb5dfb3 Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Thu, 2 Nov 2023 02:53:51 -0700 Subject: [PATCH 2/4] Update primitive_docs.rs --- library/core/src/primitive_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 8524177149f6c..611b9e26132e2 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -873,7 +873,7 @@ mod prim_array {} /// Slices can be used to construct "slice-based dynamically-sized types", also /// known as "slice DSTs" or "custom DSTs": /// -/// ```rust +/// ``` /// struct SliceDst { /// a: u8, /// b: u16, @@ -885,7 +885,7 @@ mod prim_array {} /// References to slice DSTs encode the number of elements in the trailing slice /// field: /// -/// ```rust +/// ``` /// # struct SliceDst { a: u8, b: u16, c: [u32] } /// let pointer_size = std::mem::size_of::<&u8>(); /// assert_eq!(2 * pointer_size, std::mem::size_of::<&SliceDst>()); From e2523fd992f70f322a31cfe3c46cd0b1f39f6307 Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Tue, 5 Mar 2024 12:45:43 -0800 Subject: [PATCH 3/4] Remove "if it compiles successfully" language --- library/core/src/primitive_docs.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 611b9e26132e2..67bab32ffa8d3 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -891,9 +891,8 @@ mod prim_array {} /// assert_eq!(2 * pointer_size, std::mem::size_of::<&SliceDst>()); /// ``` /// -/// Rust guarantees that, if a slice DST compiles successfully, then the instance -/// of that type with 0 elements in its trailing slice is no more than `isize::MAX` -/// bytes in size. +/// Rust guarantees that, for all slice DSTs, the instance of that type with 0 +/// elements in its trailing slice is no more than `isize::MAX` bytes in size. /// /// [`Hash`]: core::hash::Hash /// [`.iter`]: slice::iter From 16ee065113ca17654d538a9bc2b8fdb0132bf2df Mon Sep 17 00:00:00 2001 From: Joshua Liebow-Feeser Date: Tue, 5 Mar 2024 12:46:53 -0800 Subject: [PATCH 4/4] Improve grammar --- library/core/src/primitive_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 67bab32ffa8d3..9c3293898b408 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -891,8 +891,8 @@ mod prim_array {} /// assert_eq!(2 * pointer_size, std::mem::size_of::<&SliceDst>()); /// ``` /// -/// Rust guarantees that, for all slice DSTs, the instance of that type with 0 -/// elements in its trailing slice is no more than `isize::MAX` bytes in size. +/// Rust guarantees that, if `T` is a slice DST, the instance of `T` with 0 elements +/// in its trailing slice is no more than `isize::MAX` bytes in size. /// /// [`Hash`]: core::hash::Hash /// [`.iter`]: slice::iter