From 73e5b1d1b881cac24dfbb4dcd81d5cf3ac7d7ba7 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Fri, 5 Jun 2026 10:00:22 -0700 Subject: [PATCH] Improve documentation of `align_of` and `Alignment`. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * The documentation for `align_of_val()` and `Alignment::of_val()` did not explain its use in interacting with `dyn` types, and even contained the false statement that “Every reference to a value of the type `T` must be a multiple of this number”. This change removes that statement from everything except `align_of()`, and adds a mention of, and example code for, getting the alignment of a `dyn` value. * The documentation for `align_of_val_raw()` did not explain how it relates to other functions in the family. Now it does. * Added a caveat that the alignment of `i32` is not always 4, despite the examples asserting this. --- library/core/src/mem/alignment.rs | 36 ++++++++++++++++++++++++++-- library/core/src/mem/mod.rs | 40 +++++++++++++++++++++++++++---- 2 files changed, 69 insertions(+), 7 deletions(-) diff --git a/library/core/src/mem/alignment.rs b/library/core/src/mem/alignment.rs index 08ce7fcd55523..8f453685a6f92 100644 --- a/library/core/src/mem/alignment.rs +++ b/library/core/src/mem/alignment.rs @@ -58,7 +58,13 @@ impl Alignment { /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. /// - /// Every reference to a value of the type `T` must be a multiple of this number. + /// This function is identical to [`Alignment::of::()`][Self::of] whenever + /// T: [Sized], + /// but also supports determining the alignment required by a `dyn Trait` value, which is the + /// alignment of the underlying concrete type. + /// + /// This provides the same numerical value as [`align_of_val`], + /// but in an `Alignment` instead of a `usize`. /// /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface /// @@ -70,6 +76,25 @@ impl Alignment { /// /// assert_eq!(Alignment::of_val(&5i32).as_usize(), 4); /// ``` + /// + /// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; + /// that is, the above assertion does not pass on all platforms.) + /// + /// `dyn` types may have different alignments for different values; + /// `Alignment::of_val()` can be used to learn those alignments: + /// + /// ``` + /// #![feature(ptr_alignment_type)] + /// use std::mem::Alignment; + /// + /// let a: &dyn ToString = &1234u16; + /// let b: &dyn ToString = &String::from("abcd"); + /// + /// assert_eq!(Alignment::of_val(a), Alignment::of::()); + /// assert_eq!(Alignment::of_val(b), Alignment::of::()); + /// ``` + /// + /// [type-layout]: ../../reference/type-layout.html#r-layout.primitive #[inline] #[must_use] #[unstable(feature = "ptr_alignment_type", issue = "102070")] @@ -81,7 +106,9 @@ impl Alignment { /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. /// - /// Every reference to a value of the type `T` must be a multiple of this number. + /// This function is identical to [`Alignment::of_val()`], except that it can be used with raw + /// pointers in situations where it would be unsound or undesirable to convert them to + /// [`&` references][primitive@reference] and impose the aliasing rules that come with that. /// /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface /// @@ -117,6 +144,11 @@ impl Alignment { /// /// assert_eq!(unsafe { Alignment::of_val_raw(&5i32) }.as_usize(), 4); /// ``` + /// + /// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; + /// that is, the above assertion does not pass on all platforms.) + /// + /// [type-layout]: ../../reference/type-layout.html#r-layout.primitive #[inline] #[must_use] #[unstable(feature = "ptr_alignment_type", issue = "102070")] diff --git a/library/core/src/mem/mod.rs b/library/core/src/mem/mod.rs index 62c612e7ba2a6..9a54cfad40b1a 100644 --- a/library/core/src/mem/mod.rs +++ b/library/core/src/mem/mod.rs @@ -506,7 +506,7 @@ pub fn min_align_of_val(val: &T) -> usize { unsafe { intrinsics::align_of_val(val) } } -/// Returns the [ABI]-required minimum alignment of a type in bytes. +/// Returns the [ABI]-required minimum alignment of a type, in bytes. /// /// Every reference to a value of the type `T` must be a multiple of this number. /// @@ -519,6 +519,11 @@ pub fn min_align_of_val(val: &T) -> usize { /// ``` /// assert_eq!(4, align_of::()); /// ``` +/// +/// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; +/// that is, the above assertion does not pass on all platforms.) +/// +/// [type-layout]: ../../reference/type-layout.html#r-layout.primitive #[inline(always)] #[must_use] #[stable(feature = "rust1", since = "1.0.0")] @@ -529,10 +534,12 @@ pub const fn align_of() -> usize { ::ALIGN } -/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to in +/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to, in /// bytes. /// -/// Every reference to a value of the type `T` must be a multiple of this number. +/// This function is identical to [`align_of::()`][align_of] whenever T: [Sized], +/// but also supports determining the alignment required by a `dyn Trait` value, which is the +/// alignment of the underlying concrete type. /// /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface /// @@ -541,6 +548,22 @@ pub const fn align_of() -> usize { /// ``` /// assert_eq!(4, align_of_val(&5i32)); /// ``` +/// +/// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; +/// that is, this example assertion does not pass on all platforms.) +/// +/// `dyn` types may have different alignments for different values; +/// `align_of_val` can be used to learn those alignments: +/// +/// ``` +/// let a: &dyn ToString = &1234u16; +/// let b: &dyn ToString = &String::from("abcd"); +/// +/// assert_eq!(align_of_val(a), align_of::()); +/// assert_eq!(align_of_val(b), align_of::()); +/// ``` +/// +/// [type-layout]: ../../reference/type-layout.html#r-layout.primitive #[inline] #[must_use] #[stable(feature = "rust1", since = "1.0.0")] @@ -550,10 +573,12 @@ pub const fn align_of_val(val: &T) -> usize { unsafe { intrinsics::align_of_val(val) } } -/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to in +/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to, in /// bytes. /// -/// Every reference to a value of the type `T` must be a multiple of this number. +/// This function is identical to [`align_of_val()`], except that it can be used with raw pointers +/// in situations where it would be unsound or undesirable to convert them to +/// [`&` references][primitive@reference] and impose the aliasing rules that come with that. /// /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface /// @@ -589,6 +614,11 @@ pub const fn align_of_val(val: &T) -> usize { /// /// assert_eq!(4, unsafe { mem::align_of_val_raw(&5i32) }); /// ``` +/// +/// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; +/// that is, the above assertion does not pass on all platforms.) +/// +/// [type-layout]: ../../reference/type-layout.html#r-layout.primitive #[inline] #[must_use] #[unstable(feature = "layout_for_ptr", issue = "69835")]