Text of rust.docs.kernel.org › next › src › core › mem › alignment.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

alignment.rs - source

Skip to main content core/mem/ alignment.rs 1 #![allow(clippy::enum_clike_unportable_variant)] 2 3 use crate ::num::NonZero ; 4 use crate ::ub_checks::assert_unsafe_precondition ; 5 use crate ::{ cmp , fmt , hash , mem , num }; 6 7 /// A type storing a `usize` which is a power of two, and thus 8 /// represents a possible alignment in the Rust abstract machine. 9 /// 10 /// Note that particularly large alignments, while representable in this type, 11 /// are likely not to be supported by actual allocators and linkers.

12 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 13 #[derive( Copy )] 14 #[derive_const( Clone , PartialEq , Eq )] 15 #[repr(transparent)] 16 pub struct Alignment { 17 // This field is never used directly (nor is the enum), 18 // as it's just there to convey the validity invariant. 19 // (Hopefully it'll eventually be a pattern type instead.) 20 _inner_repr_trick: AlignmentEnum , 21 } 22 23 // Alignment is `repr(usize)`, but via extra steps.

24 const _ : () = assert! (size_of::<Alignment>() == size_of::<usize>()); 25 const _ : () = assert! (align_of::<Alignment>() == align_of::<usize>()); 26 27 fn _alignment_can_be_structurally_matched(a: Alignment ) -> bool { 28 matches! (a, Alignment::MIN) 29 } 30 31 impl Alignment { 32 /// The smallest possible alignment, 1. 33 /// 34 /// All addresses are always aligned at least this much. 35 /// 36 /// # Examples 37 /// 38 /// ``` 39 /// use std::mem::Alignment; 40 /// 41 /// assert_eq!(Alignment::MIN.as_usize(), 1); 42 /// ``` 43 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 44 pub const MIN: Self = Self :: new ( 1 ). unwrap (); 45 46 /// Returns the alignment for a type.

47 /// 48 /// This provides the same numerical value as [`align_of`], 49 /// but in an `Alignment` instead of a `usize`. 50 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 51 #[rustc_const_stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 52 #[inline] 53 #[must_use] 54 pub const fn of<T>() -> Self { 55 <T as mem::SizedTypeProperties>:: ALIGNMENT 56 } 57 58 /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to.

59 /// 60 /// This function is identical to [`Alignment::of::<T>()`][Self::of] whenever 61 /// <code>T: [Sized]</code>, 62 /// but also supports determining the alignment required by a `dyn Trait` value, which is the 63 /// alignment of the underlying concrete type. 64 /// 65 /// This provides the same numerical value as [`align_of_val`], 66 /// but in an `Alignment` instead of a `usize`. 67 /// 68 /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface 69 /// 70 /// # Examples 71 /// 72 /// ``` 73 /// use std::mem::Alignment; 74 /// 75 /// assert_eq!(Alignment::of_val(&5i32).as_usize(), 4); 76 /// ``` 77 /// 78 /// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; 79 /// that is, the above assertion does not pass on all platforms.) 80 /// 81 /// `dyn` types may have different alignments for different values; 82 /// `Alignment::of_val()` can be used to learn those alignments: 83 /// 84 /// ``` 85 /// use std::mem::Alignment; 86 /// 87 /// let a: &dyn ToString = &1234u16; 88 /// let b: &dyn ToString = &String::from("abcd"); 89 /// 90 /// assert_eq!(Alignment::of_val(a), Alignment::of::<u16>()); 91 /// assert_eq!(Alignment::of_val(b), Alignment::of::<String>()); 92 /// ``` 93 /// 94 /// [type-layout]: ../../reference/type-layout.html#r-layout.primitive 95 #[inline] 96 #[must_use] 97 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 98 #[rustc_const_stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 99 pub const fn of_val<T: ?

Sized >(val: & T) -> Self { 100 let align = mem:: align_of_val ( val ); 101 // SAFETY: `align_of_val` returns valid alignment 102 unsafe { Alignment :: new_unchecked ( align ) } 103 } 104 105 /// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to. 106 /// 107 /// This function is identical to [`Alignment::of_val()`], except that it can be used with raw 108 /// pointers in situations where it would be unsound or undesirable to convert them to 109 /// [`&` references][primitive@reference] and impose the aliasing rules that come with that.

110 /// 111 /// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface 112 /// 113 /// # Safety 114 /// 115 /// This function is safe to call if the pointer is safe to reborrow as `&T` 116 /// (in which case you could also call [`of_val`][Self::of_val]). 117 /// Otherwise, the following conditions must hold: 118 /// 119 /// - If `T` is `Sized`, this function is always safe to call. 120 /// - If the unsized tail of `T` is: 121 /// - a [slice], then the length of the slice tail must be an initialized 122 /// integer, and the size of the *entire value* 123 /// (dynamic tail length + statically sized prefix) must fit in `isize`.

124 /// For the special case where the dynamic tail length is 0, this function 125 /// is safe to call. 126 /// - a [trait object], then the vtable part of the pointer must point 127 /// to a valid vtable acquired by an unsizing coercion, and the size 128 /// of the *entire value* (dynamic tail length + statically sized prefix) 129 /// must fit in `isize`. 130 /// - an (unstable) [extern type], then this function is always safe to 131 /// call, but may panic or otherwise return the wrong value, as the 132 /// extern type's layout is not known.

This is the same behavior as 133 /// [`Alignment::of_val`] on a reference to a type with an extern type tail. 134 /// - otherwise, it is conservatively not allowed to call this function. 135 /// 136 /// [trait object]: ../../book/ch17-02-trait-objects.html 137 /// [extern type]: ../../unstable-book/language-features/extern-types.html 138 /// 139 /// # Examples 140 /// 141 /// ``` 142 /// use std::mem::Alignment; 143 /// 144 /// assert_eq!(unsafe { Alignment::of_val_raw(&5i32) }.as_usize(), 4); 145 /// ``` 146 /// 147 /// (Caution: [it is not guaranteed][type-layout] that the alignment of `i32` is `4`; 148 /// that is, the above assertion does not pass on all platforms.) 149 /// 150 /// [type-layout]: ../../reference/type-layout.html#r-layout.primitive 151 #[inline] 152 #[must_use] 153 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 154 #[rustc_const_stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 155 pub const unsafe fn of_val_raw<T: ?

Sized >(val: *const T) -> Self { 156 // SAFETY: precondition propagated to the caller 157 let align = unsafe { mem:: align_of_val_raw ( val ) }; 158 // SAFETY: `align_of_val_raw` returns valid alignment 159 unsafe { Alignment :: new_unchecked ( align ) } 160 } 161 162 /// Creates an `Alignment` from a `usize`, or returns `None` if it's 163 /// not a power of two. 164 /// 165 /// Note that `0` is not a power of two, nor a valid alignment.

166 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 167 #[rustc_const_stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 168 #[inline] 169 pub const fn new(align: usize ) -> Option < Self > { 170 if align . is_power_of_two () { 171 // SAFETY: Just checked it only has one bit set 172 Some ( unsafe { Self :: new_unchecked ( align ) }) 173 } else { 174 None 175 } 176 } 177 178 /// Creates an `Alignment` from a power-of-two `usize`.

179 /// 180 /// # Safety 181 /// 182 /// `align` must be a power of two. 183 /// 184 /// Equivalently, it must be `1 << exp` for some `exp` in `0..usize::BITS`. 185 /// It must *not* be zero. 186 #[stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 187 #[rustc_const_stable(feature = "alignment_type" , since = "CURRENT_RUSTC_VERSION" )] 188 #[inline] 189 #[track_caller] 190 pub const unsafe fn new_unchecked(align: usize ) -> Self { 191 assert_unsafe_precondition! ( 192 check_language_ub, 193 "Alignment::new_unchecked requires a power of

The rest of this page is on the live site.