1use crate::num::NonZero;
2#[cfg(debug_assertions)]
3use crate::ub_checks::assert_unsafe_precondition;
4use crate::{cmp, fmt, hash, mem, num};
5
6/// A type storing a `usize` which is a power of two, and thus
7/// represents a possible alignment in the Rust abstract machine.
8///
9/// Note that particularly large alignments, while representable in this type,
10/// are likely not to be supported by actual allocators and linkers.
11#[unstable(feature = "ptr_alignment_type", issue = "102070")]
12#[derive(Copy, Clone, PartialEq, Eq)]
13#[repr(transparent)]
14pub struct Alignment(AlignmentEnum);
15
16// Alignment is `repr(usize)`, but via extra steps.
17const _: () = assert!(mem::size_of::<Alignment>() == mem::size_of::<usize>());
18const _: () = assert!(mem::align_of::<Alignment>() == mem::align_of::<usize>());
19
20fn _alignment_can_be_structurally_matched(a: Alignment) -> bool {
21 matches!(a, Alignment::MIN)
22}
23
24impl Alignment {
25 /// The smallest possible alignment, 1.
26 ///
27 /// All addresses are always aligned at least this much.
28 ///
29 /// # Examples
30 ///
31 /// ```
32 /// #![feature(ptr_alignment_type)]
33 /// use std::ptr::Alignment;
34 ///
35 /// assert_eq!(Alignment::MIN.as_usize(), 1);
36 /// ```
37 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
38 pub const MIN: Self = Self(AlignmentEnum::_Align1Shl0);
39
40 /// Returns the alignment for a type.
41 ///
42 /// This provides the same numerical value as [`mem::align_of`],
43 /// but in an `Alignment` instead of a `usize`.
44 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
45 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
46 #[inline]
47 pub const fn of<T>() -> Self {
48 // SAFETY: rustc ensures that type alignment is always a power of two.
49 unsafe { Alignment::new_unchecked(mem::align_of::<T>()) }
50 }
51
52 /// Creates an `Alignment` from a `usize`, or returns `None` if it's
53 /// not a power of two.
54 ///
55 /// Note that `0` is not a power of two, nor a valid alignment.
56 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
57 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
58 #[inline]
59 pub const fn new(align: usize) -> Option<Self> {
60 if align.is_power_of_two() {
61 // SAFETY: Just checked it only has one bit set
62 Some(unsafe { Self::new_unchecked(align) })
63 } else {
64 None
65 }
66 }
67
68 /// Creates an `Alignment` from a power-of-two `usize`.
69 ///
70 /// # Safety
71 ///
72 /// `align` must be a power of two.
73 ///
74 /// Equivalently, it must be `1 << exp` for some `exp` in `0..usize::BITS`.
75 /// It must *not* be zero.
76 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
77 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
78 #[inline]
79 pub const unsafe fn new_unchecked(align: usize) -> Self {
80 #[cfg(debug_assertions)]
81 assert_unsafe_precondition!(
82 check_language_ub,
83 "Alignment::new_unchecked requires a power of two",
84 (align: usize = align) => align.is_power_of_two()
85 );
86
87 // SAFETY: By precondition, this must be a power of two, and
88 // our variants encompass all possible powers of two.
89 unsafe { mem::transmute::<usize, Alignment>(align) }
90 }
91
92 /// Returns the alignment as a [`usize`].
93 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
94 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
95 #[inline]
96 pub const fn as_usize(self) -> usize {
97 self.0 as usize
98 }
99
100 /// Returns the alignment as a <code>[NonZero]<[usize]></code>.
101 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
102 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
103 #[inline]
104 pub const fn as_nonzero(self) -> NonZero<usize> {
105 // SAFETY: All the discriminants are non-zero.
106 unsafe { NonZero::new_unchecked(self.as_usize()) }
107 }
108
109 /// Returns the base-2 logarithm of the alignment.
110 ///
111 /// This is always exact, as `self` represents a power of two.
112 ///
113 /// # Examples
114 ///
115 /// ```
116 /// #![feature(ptr_alignment_type)]
117 /// use std::ptr::Alignment;
118 ///
119 /// assert_eq!(Alignment::of::<u8>().log2(), 0);
120 /// assert_eq!(Alignment::new(1024).unwrap().log2(), 10);
121 /// ```
122 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
123 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
124 #[inline]
125 pub const fn log2(self) -> u32 {
126 self.as_nonzero().trailing_zeros()
127 }
128
129 /// Returns a bit mask that can be used to match this alignment.
130 ///
131 /// This is equivalent to `!(self.as_usize() - 1)`.
132 ///
133 /// # Examples
134 ///
135 /// ```
136 /// #![feature(ptr_alignment_type)]
137 /// #![feature(ptr_mask)]
138 /// use std::ptr::{Alignment, NonNull};
139 ///
140 /// #[repr(align(1))] struct Align1(u8);
141 /// #[repr(align(2))] struct Align2(u16);
142 /// #[repr(align(4))] struct Align4(u32);
143 /// let one = <NonNull<Align1>>::dangling().as_ptr();
144 /// let two = <NonNull<Align2>>::dangling().as_ptr();
145 /// let four = <NonNull<Align4>>::dangling().as_ptr();
146 ///
147 /// assert_eq!(four.mask(Alignment::of::<Align1>().mask()), four);
148 /// assert_eq!(four.mask(Alignment::of::<Align2>().mask()), four);
149 /// assert_eq!(four.mask(Alignment::of::<Align4>().mask()), four);
150 /// assert_ne!(one.mask(Alignment::of::<Align4>().mask()), one);
151 /// ```
152 #[unstable(feature = "ptr_alignment_type", issue = "102070")]
153 #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")]
154 #[inline]
155 pub const fn mask(self) -> usize {
156 // SAFETY: The alignment is always nonzero, and therefore decrementing won't overflow.
157 !(unsafe { self.as_usize().unchecked_sub(1) })
158 }
159}
160
161#[unstable(feature = "ptr_alignment_type", issue = "102070")]
162impl fmt::Debug for Alignment {
163 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
164 write!(f, "{:?} (1 << {:?})", self.as_nonzero(), self.log2())
165 }
166}
167
168#[unstable(feature = "ptr_alignment_type", issue = "102070")]
169impl TryFrom<NonZero<usize>> for Alignment {
170 type Error = num::TryFromIntError;
171
172 #[inline]
173 fn try_from(align: NonZero<usize>) -> Result<Alignment, Self::Error> {
174 align.get().try_into()
175 }
176}
177
178#[unstable(feature = "ptr_alignment_type", issue = "102070")]
179impl TryFrom<usize> for Alignment {
180 type Error = num::TryFromIntError;
181
182 #[inline]
183 fn try_from(align: usize) -> Result<Alignment, Self::Error> {
184 Self::new(align).ok_or(err:num::TryFromIntError(()))
185 }
186}
187
188#[unstable(feature = "ptr_alignment_type", issue = "102070")]
189impl From<Alignment> for NonZero<usize> {
190 #[inline]
191 fn from(align: Alignment) -> NonZero<usize> {
192 align.as_nonzero()
193 }
194}
195
196#[unstable(feature = "ptr_alignment_type", issue = "102070")]
197impl From<Alignment> for usize {
198 #[inline]
199 fn from(align: Alignment) -> usize {
200 align.as_usize()
201 }
202}
203
204#[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")]
205#[unstable(feature = "ptr_alignment_type", issue = "102070")]
206impl cmp::Ord for Alignment {
207 #[inline]
208 fn cmp(&self, other: &Self) -> cmp::Ordering {
209 self.as_nonzero().get().cmp(&other.as_nonzero().get())
210 }
211}
212
213#[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")]
214#[unstable(feature = "ptr_alignment_type", issue = "102070")]
215impl cmp::PartialOrd for Alignment {
216 #[inline]
217 fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
218 Some(self.cmp(other))
219 }
220}
221
222#[unstable(feature = "ptr_alignment_type", issue = "102070")]
223impl hash::Hash for Alignment {
224 #[inline]
225 fn hash<H: hash::Hasher>(&self, state: &mut H) {
226 self.as_nonzero().hash(state)
227 }
228}
229
230/// Returns [`Alignment::MIN`], which is valid for any type.
231#[unstable(feature = "ptr_alignment_type", issue = "102070")]
232impl Default for Alignment {
233 fn default() -> Alignment {
234 Alignment::MIN
235 }
236}
237
238#[cfg(target_pointer_width = "16")]
239#[derive(Copy, Clone, PartialEq, Eq)]
240#[repr(u16)]
241enum AlignmentEnum {
242 _Align1Shl0 = 1 << 0,
243 _Align1Shl1 = 1 << 1,
244 _Align1Shl2 = 1 << 2,
245 _Align1Shl3 = 1 << 3,
246 _Align1Shl4 = 1 << 4,
247 _Align1Shl5 = 1 << 5,
248 _Align1Shl6 = 1 << 6,
249 _Align1Shl7 = 1 << 7,
250 _Align1Shl8 = 1 << 8,
251 _Align1Shl9 = 1 << 9,
252 _Align1Shl10 = 1 << 10,
253 _Align1Shl11 = 1 << 11,
254 _Align1Shl12 = 1 << 12,
255 _Align1Shl13 = 1 << 13,
256 _Align1Shl14 = 1 << 14,
257 _Align1Shl15 = 1 << 15,
258}
259
260#[cfg(target_pointer_width = "32")]
261#[derive(Copy, Clone, PartialEq, Eq)]
262#[repr(u32)]
263enum AlignmentEnum {
264 _Align1Shl0 = 1 << 0,
265 _Align1Shl1 = 1 << 1,
266 _Align1Shl2 = 1 << 2,
267 _Align1Shl3 = 1 << 3,
268 _Align1Shl4 = 1 << 4,
269 _Align1Shl5 = 1 << 5,
270 _Align1Shl6 = 1 << 6,
271 _Align1Shl7 = 1 << 7,
272 _Align1Shl8 = 1 << 8,
273 _Align1Shl9 = 1 << 9,
274 _Align1Shl10 = 1 << 10,
275 _Align1Shl11 = 1 << 11,
276 _Align1Shl12 = 1 << 12,
277 _Align1Shl13 = 1 << 13,
278 _Align1Shl14 = 1 << 14,
279 _Align1Shl15 = 1 << 15,
280 _Align1Shl16 = 1 << 16,
281 _Align1Shl17 = 1 << 17,
282 _Align1Shl18 = 1 << 18,
283 _Align1Shl19 = 1 << 19,
284 _Align1Shl20 = 1 << 20,
285 _Align1Shl21 = 1 << 21,
286 _Align1Shl22 = 1 << 22,
287 _Align1Shl23 = 1 << 23,
288 _Align1Shl24 = 1 << 24,
289 _Align1Shl25 = 1 << 25,
290 _Align1Shl26 = 1 << 26,
291 _Align1Shl27 = 1 << 27,
292 _Align1Shl28 = 1 << 28,
293 _Align1Shl29 = 1 << 29,
294 _Align1Shl30 = 1 << 30,
295 _Align1Shl31 = 1 << 31,
296}
297
298#[cfg(target_pointer_width = "64")]
299#[derive(Copy, Clone, PartialEq, Eq)]
300#[repr(u64)]
301enum AlignmentEnum {
302 _Align1Shl0 = 1 << 0,
303 _Align1Shl1 = 1 << 1,
304 _Align1Shl2 = 1 << 2,
305 _Align1Shl3 = 1 << 3,
306 _Align1Shl4 = 1 << 4,
307 _Align1Shl5 = 1 << 5,
308 _Align1Shl6 = 1 << 6,
309 _Align1Shl7 = 1 << 7,
310 _Align1Shl8 = 1 << 8,
311 _Align1Shl9 = 1 << 9,
312 _Align1Shl10 = 1 << 10,
313 _Align1Shl11 = 1 << 11,
314 _Align1Shl12 = 1 << 12,
315 _Align1Shl13 = 1 << 13,
316 _Align1Shl14 = 1 << 14,
317 _Align1Shl15 = 1 << 15,
318 _Align1Shl16 = 1 << 16,
319 _Align1Shl17 = 1 << 17,
320 _Align1Shl18 = 1 << 18,
321 _Align1Shl19 = 1 << 19,
322 _Align1Shl20 = 1 << 20,
323 _Align1Shl21 = 1 << 21,
324 _Align1Shl22 = 1 << 22,
325 _Align1Shl23 = 1 << 23,
326 _Align1Shl24 = 1 << 24,
327 _Align1Shl25 = 1 << 25,
328 _Align1Shl26 = 1 << 26,
329 _Align1Shl27 = 1 << 27,
330 _Align1Shl28 = 1 << 28,
331 _Align1Shl29 = 1 << 29,
332 _Align1Shl30 = 1 << 30,
333 _Align1Shl31 = 1 << 31,
334 _Align1Shl32 = 1 << 32,
335 _Align1Shl33 = 1 << 33,
336 _Align1Shl34 = 1 << 34,
337 _Align1Shl35 = 1 << 35,
338 _Align1Shl36 = 1 << 36,
339 _Align1Shl37 = 1 << 37,
340 _Align1Shl38 = 1 << 38,
341 _Align1Shl39 = 1 << 39,
342 _Align1Shl40 = 1 << 40,
343 _Align1Shl41 = 1 << 41,
344 _Align1Shl42 = 1 << 42,
345 _Align1Shl43 = 1 << 43,
346 _Align1Shl44 = 1 << 44,
347 _Align1Shl45 = 1 << 45,
348 _Align1Shl46 = 1 << 46,
349 _Align1Shl47 = 1 << 47,
350 _Align1Shl48 = 1 << 48,
351 _Align1Shl49 = 1 << 49,
352 _Align1Shl50 = 1 << 50,
353 _Align1Shl51 = 1 << 51,
354 _Align1Shl52 = 1 << 52,
355 _Align1Shl53 = 1 << 53,
356 _Align1Shl54 = 1 << 54,
357 _Align1Shl55 = 1 << 55,
358 _Align1Shl56 = 1 << 56,
359 _Align1Shl57 = 1 << 57,
360 _Align1Shl58 = 1 << 58,
361 _Align1Shl59 = 1 << 59,
362 _Align1Shl60 = 1 << 60,
363 _Align1Shl61 = 1 << 61,
364 _Align1Shl62 = 1 << 62,
365 _Align1Shl63 = 1 << 63,
366}
367