alignment.rs - source
Description: Source of the Rust file `library/core/src/ptr/alignment.rs`.

#
core/ptr/
alignment.rs

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