core/ptr/
alignment.rs

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

core/ptr/
alignment.rs
