ab_io_type/

trivial_type.rs

use crate::IoType;
use crate::alignment::Alignment;
use crate::metadata::{IoTypeMetadataKind, MAX_METADATA_CAPACITY, concat_metadata_sources};
use crate::unaligned::Unaligned;
pub use ab_io_type_derive::TrivialType;
use core::ops::{Deref, DerefMut};
use core::ptr::NonNull;
use core::{ptr, slice};

const SIZE_OF<T>: usize = size_of::<T>();
/// Ensures the number of array elements (encoded in metadata) and array size fit into `u32`
const SUPPORTED_ARRAY<T, const N: usize>: usize = {
    assert!(
        u32::MAX as usize >= N,
        "Number of array elements must be smaller than 2^32"
    );
    assert!(
        u32::MAX as usize >= size_of::<[T; N]>(),
        "Type size must be smaller than 2^32"
    );
    0
};
/// Ensures `T` is not zero-sized, which some containers can't represent
pub(crate) const NON_ZERO_SIZED<T: TrivialType>: usize = {
    assert!(T::SIZE > 0, "Zero-sized types are not supported");
    0
};

// TODO: Make this a `const` trait, with `const` impls generated by the derive, once const traits
//  are stable, deriving crates would need `#![feature(const_trait_impl)]` otherwise:
//  https://github.com/rust-lang/rust/issues/143874
/// Simple wrapper data type that is designed in such a way that its serialization/deserialization
/// is the same as the type itself.
///
/// Serialization takes the bytes of a value. Deserialization parses bytes: the parsing step checks
/// that they are a valid value of the type, which is a length check for types that accept every
/// bit pattern (see [`AnyBitPattern`]). Bytes that are not aligned for the type are parsed with the
/// methods of [`Unaligned`], like `Unaligned::<T>::try_from_bytes()`.
///
/// A valid value is one whose every field is a valid value of its type, like `0` or `1` for a
/// `bool` and the index of a variant for the discriminant of an enum, and that satisfies the
/// invariants `unsafe` code relies on. Parsing may reject more, like a length of
/// `FixedCapacityElements` above its capacity, but doesn't check encoding rules, like the bytes of
/// its length prefix after the length.
///
/// # Safety
/// * There is no padding, every byte is initialized and there is no interior mutability
/// * The alignment is at most [`Alignment::MAX`]
/// * [`Self::SIZE`] is not overridden
/// * [`Self::ALIGNMENT`] is the alignment that [`Self::METADATA`] decodes to, and it is at least
///   `align_of::<Self>()`
/// * The parsing step `parse_step::<ALIGNED>()` returns `Some((value, remainder))` only if `bytes`
///   start with `size_of::<Self>()` bytes that are a valid value of `Self`, `value` points to the
///   beginning of `bytes` and `remainder` is the rest of `bytes` after those bytes. This holds for
///   both flavours: the aligned one (`ALIGNED` is `true`) gets `bytes` aligned for `Self`, the
///   unaligned one gets `bytes` of any alignment
///
/// Implementations are expected to be composites of existing `TrivialType`s without custom
/// alignment, whose alignment is then at most [`Alignment::MAX`] as well. Prefer
/// `#[derive(TrivialType)]`, which upholds this contract.
///
/// # Deriving
/// `#[derive(TrivialType)]` supports structs and enums and checks the following requirements at
/// compile time:
/// * no generic parameters, and types of all fields implement `TrivialType`
/// * structs are `#[repr(C)]` or `#[repr(transparent)]` without other options
/// * enums are `#[repr(u8)]` without other options
/// * no `#[repr(align(N))]` or `#[repr(packed)]` in any `#[repr(..)]` attribute, [`Unaligned`] can
///   be used to reduce the alignment of a field to one byte instead
/// * no implicit padding, explicit `padding: [u8; N]` fields can be added where necessary. Padding
///   is determined by [`TrivialType::ALIGNMENT`] of the field types. Each variant of an enum is
///   laid out like a `#[repr(C)]` struct with the discriminant as the first field, so fields of all
///   variants must have the same total size
/// * explicit discriminants of enum variants are equal to the index of the variant, metadata
///   identifies variants by their index and doesn't record discriminants
/// * at most 255 fields in a struct or enum variant and at most 255 variants in an enum, names of
///   the type, its fields and variants are at most 255 bytes long
/// * size is smaller than 2^32 bytes
/// * metadata, including metadata of field types, is at most [`MAX_METADATA_CAPACITY`] bytes,
///   otherwise const evaluation panics with an opaque error
/// * structs parse their fields in order, enums check the discriminant and parse the fields of that
///   variant
/// * deriving means that any combination of valid field values is a valid value of the type,
///   private fields and `#[non_exhaustive]` included, because parsing creates values without
///   calling constructors, unless `#[trivial_type(validate = path)]` rejects it
/// * structs implement [`AnyBitPatternMarker`] when all their fields do, unless they use
///   `#[trivial_type(validate = path)]`
///
/// Invariants that `unsafe` code relies on are checked with `#[trivial_type(validate = path)]`.
/// `path` is called as `path(value: &Self) -> bool` after all fields were parsed and must return
/// `false` for every value that `unsafe` code relying on the invariants can't handle. It must not
/// panic, since parsing is used in code that is verified not to panic, and a `const fn` is
/// recommended, the derive may become `const` later. Such types don't implement
/// [`AnyBitPatternMarker`].
///
/// It is called by every parsing method, including those of arrays of the type, of [`Unaligned`]
/// and of containers through [`IoType::try_from_ptr()`] and [`IoType::try_from_mut_ptr()`]. The
/// unsafe methods that skip parsing, [`IoType::from_ptr()`], [`IoType::from_mut_ptr()`] and derives
/// of other crates, like SCALE's `Decode` and serde's `Deserialize`, don't call it.
pub unsafe trait TrivialType
where
    Self: Copy + 'static,
{
    // TODO: Make it `final` once supported:
    //  https://internals.rust-lang.org/t/final-associated-constants/24655
    const SIZE: u32 = {
        assert!(
            u32::MAX as usize >= size_of::<Self>(),
            "Type size must be smaller than 2^32"
        );
        size_of::<Self>() as u32
    };
    /// Alignment of the type in metadata.
    ///
    /// Integers and `bool` are aligned to their size, `()` and [`Unaligned`] to 1 byte, other types
    /// to the largest alignment of their contents. It is never smaller than `align_of::<Self>()`,
    /// so memory aligned to it is aligned for `Self`.
    const ALIGNMENT: Alignment;
    /// Data structure metadata in binary form, describing shape and types of the contents, see
    /// [`IoTypeMetadataKind`] for encoding details.
    const METADATA: &[u8];

    /// Parse the beginning of `bytes`, which are aligned for `Self` if `ALIGNED`.
    ///
    /// Returns the value and the remaining bytes, or `None` if `bytes` are shorter than the type or
    /// don't start with a valid value. `#[derive(TrivialType)]` implements it, the other parsing
    /// methods are built on it. Values in memory that is not aligned for `Self` are read with the
    /// methods of [`Unaligned<Self>`], like `Unaligned::<Self>::try_from_bytes()`.
    ///
    /// Both flavours must accept the same values. The aligned one can use aligned loads, which
    /// matters on targets without fast unaligned access, where unaligned loads wider than a byte
    /// compile to several byte loads.
    ///
    /// # Safety
    /// If `ALIGNED`, `bytes` are aligned for `Self`.
    #[doc(hidden)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])>;

    /// Parse the beginning of aligned `bytes`, returns the value and the remaining bytes.
    ///
    /// Returns `None` if `bytes` are not aligned for `Self`, are too short or don't start with a
    /// valid value.
    #[inline(always)]
    final fn try_from_bytes(bytes: &[u8]) -> Option<(&Self, &[u8])> {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        // SAFETY: Aligned as checked above
        let (_value, remainder) = unsafe { Self::parse_step::<true>(bytes) }?;
        // SAFETY: `bytes` start with a valid value of `Self` (parsing step contract), aligned as
        // checked above
        let value = unsafe { bytes.as_ptr().cast::<Self>().as_ref_unchecked() };
        Some((value, remainder))
    }

    /// Like [`Self::try_from_bytes()`], but returns `None` if there are more bytes than the value
    #[inline(always)]
    final fn try_from_bytes_exact(bytes: &[u8]) -> Option<&Self> {
        let (value, remainder) = Self::try_from_bytes(bytes)?;
        remainder.is_empty().then_some(value)
    }

    /// Like [`Self::try_from_bytes()`], but returns an exclusive reference.
    ///
    /// Only valid values of `Self` can be written through it, so the bytes stay a valid value.
    #[inline(always)]
    final fn try_from_bytes_mut(bytes: &mut [u8]) -> Option<(&mut Self, &mut [u8])> {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        // SAFETY: Aligned as checked above
        unsafe { Self::parse_step::<true>(bytes) }?;
        let (value, remainder) = bytes.split_at_mut_checked(size_of::<Self>())?;
        // SAFETY: `bytes` start with a valid value of `Self` (parsing step contract), aligned as
        // checked above, only valid values of `Self` can be written through the reference, and
        // they have no padding, so the bytes stay initialized. It is derived from `bytes`, not
        // from the shared reference the parsing step returned.
        let value = unsafe { value.as_mut_ptr().cast::<Self>().as_mut_unchecked() };
        Some((value, remainder))
    }

    /// Like [`Self::try_from_bytes_mut()`], but returns `None` if there are more bytes than the
    /// value
    #[inline(always)]
    final fn try_from_bytes_mut_exact(bytes: &mut [u8]) -> Option<&mut Self> {
        let (value, remainder) = Self::try_from_bytes_mut(bytes)?;
        remainder.is_empty().then_some(value)
    }

    /// Create a reference to a value at the beginning of aligned `bytes`, returns the value and
    /// the remaining bytes.
    ///
    /// Returns `None` if `bytes` are not aligned for `Self` or are too short. Unlike
    /// [`Self::try_from_bytes()`] it doesn't parse the bytes, since any bytes are a valid value.
    #[inline(always)]
    final fn from_bytes(bytes: &[u8]) -> Option<(&Self, &[u8])>
    where
        Self: AnyBitPattern,
    {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        let (value, remainder) = bytes.split_at_checked(size_of::<Self>())?;
        // SAFETY: `value` is `size_of::<Self>()` initialized bytes, aligned as checked above, and
        // any of them are a valid value of `Self` (`AnyBitPatternMarker`)
        let value = unsafe { value.as_ptr().cast::<Self>().as_ref_unchecked() };
        Some((value, remainder))
    }

    /// Like [`Self::from_bytes()`], but returns `None` if there are more bytes than the value
    #[inline(always)]
    final fn from_bytes_exact(bytes: &[u8]) -> Option<&Self>
    where
        Self: AnyBitPattern,
    {
        let (value, remainder) = Self::from_bytes(bytes)?;
        remainder.is_empty().then_some(value)
    }

    /// Similar to [`Self::from_bytes()`], but for any type and without any checks
    ///
    /// # Safety
    /// `bytes` are aligned for `Self` and start with a valid value of `Self`.
    #[inline(always)]
    final unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self {
        // SAFETY: Guaranteed by function contract
        unsafe { bytes.as_ptr().cast::<Self>().as_ref_unchecked() }
    }

    /// Like [`Self::from_bytes()`], but returns an exclusive reference
    #[inline(always)]
    final fn from_bytes_mut(bytes: &mut [u8]) -> Option<(&mut Self, &mut [u8])>
    where
        Self: AnyBitPattern,
    {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        let (value, remainder) = bytes.split_at_mut_checked(size_of::<Self>())?;
        // SAFETY: `value` is `size_of::<Self>()` initialized bytes, aligned as checked above, and
        // any of them are a valid value of `Self` (`AnyBitPatternMarker`), values written through
        // the reference have no padding, so the bytes stay initialized
        let value = unsafe { value.as_mut_ptr().cast::<Self>().as_mut_unchecked() };
        Some((value, remainder))
    }

    /// Like [`Self::from_bytes_mut()`], but returns `None` if there are more bytes than the value
    #[inline(always)]
    final fn from_bytes_mut_exact(bytes: &mut [u8]) -> Option<&mut Self>
    where
        Self: AnyBitPattern,
    {
        let (value, remainder) = Self::from_bytes_mut(bytes)?;
        remainder.is_empty().then_some(value)
    }

    /// Similar to [`Self::from_bytes_mut()`], but for any type and without any checks
    ///
    /// # Safety
    /// `bytes` are aligned for `Self` and start with a valid value of `Self`.
    #[inline(always)]
    final unsafe fn from_bytes_mut_unchecked(bytes: &mut [u8]) -> &mut Self {
        // SAFETY: Guaranteed by function contract
        unsafe { bytes.as_mut_ptr().cast::<Self>().as_mut_unchecked() }
    }

    /// Create a slice of `count` values at the beginning of aligned `bytes`, returns the values and
    /// the remaining bytes.
    ///
    /// Returns `None` if `bytes` are not aligned for `Self` or are too short. Like
    /// [`Self::from_bytes()`] it doesn't parse the bytes, since any bytes are a valid value.
    #[inline(always)]
    final fn slice_from_bytes(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>
    where
        Self: AnyBitPattern,
    {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        let (values, remainder) = bytes.split_at_checked(count.checked_mul(size_of::<Self>())?)?;
        // SAFETY: `values` are `count` times `size_of::<Self>()` initialized bytes, aligned as
        // checked above, and any of them are valid values of `Self` (`AnyBitPatternMarker`)
        let values = unsafe { slice::from_raw_parts(values.as_ptr().cast::<Self>(), count) };
        Some((values, remainder))
    }

    /// Like [`Self::slice_from_bytes()`], but returns an exclusive reference
    #[inline(always)]
    final fn slice_from_bytes_mut(
        bytes: &mut [u8],
        count: usize,
    ) -> Option<(&mut [Self], &mut [u8])>
    where
        Self: AnyBitPattern,
    {
        if !bytes.as_ptr().cast::<Self>().is_aligned() {
            return None;
        }
        let (values, remainder) =
            bytes.split_at_mut_checked(count.checked_mul(size_of::<Self>())?)?;
        // SAFETY: `values` are `count` times `size_of::<Self>()` initialized bytes, aligned as
        // checked above, and any of them are valid values of `Self` (`AnyBitPatternMarker`),
        // values written through the reference have no padding, so the bytes stay initialized
        let values =
            unsafe { slice::from_raw_parts_mut(values.as_mut_ptr().cast::<Self>(), count) };
        Some((values, remainder))
    }

    /// Access the underlying byte representation of a data structure
    #[inline(always)]
    final fn as_bytes(&self) -> &[u8; SIZE_OF::<Self>] {
        // SAFETY: All bits are valid for reading as bytes, see `TrivialType` description
        unsafe { ptr::from_ref(self).cast::<[u8; _]>().as_ref_unchecked() }
    }

    /// Access the underlying byte representation of a slice of values
    #[inline(always)]
    final fn slice_as_bytes(values: &[Self]) -> &[u8] {
        // SAFETY: All bits are valid for reading as bytes, see `TrivialType` description
        unsafe { slice::from_raw_parts(values.as_ptr().cast::<u8>(), size_of_val(values)) }
    }

    /// Access the underlying mutable byte representation of a data structure
    #[inline(always)]
    final fn as_bytes_mut(&mut self) -> &mut [u8; SIZE_OF::<Self>]
    where
        Self: AnyBitPattern,
    {
        // SAFETY: Any bytes written are a valid value of `Self` (`AnyBitPatternMarker`)
        unsafe { self.as_bytes_mut_unchecked() }
    }

    /// Similar to [`Self::as_bytes_mut()`], but for any type.
    ///
    /// # Safety
    /// Only bytes of a valid value of `Self` may be written to the returned array.
    #[inline(always)]
    final unsafe fn as_bytes_mut_unchecked(&mut self) -> &mut [u8; SIZE_OF::<Self>] {
        // SAFETY: All bits are valid for reading as bytes, see `TrivialType` description, only
        // bytes of a valid value are written (function contract)
        unsafe { ptr::from_mut(self).cast::<[u8; _]>().as_mut_unchecked() }
    }
}

// TODO: This trait only exists because `try_as_dyn()`, the only way to detect it in generic code,
//  skips impls whose bounds mention a type parameter inside a constant, like the array size limit
//  of `TrivialType for [T; N]`. Merge it into `AnyBitPattern` once that is fixed:
//  https://github.com/rust-lang/rust/issues/164149
/// Every bit pattern of the type is a valid value.
///
/// Together with [`TrivialType`] it provides [`AnyBitPattern`], which is the bound to use.
/// `#[derive(TrivialType)]` implements it for structs whose fields all implement it, unless they
/// use `#[trivial_type(validate = path)]`.
///
/// # Safety
/// Every pattern of `size_of::<Self>()` initialized bytes is a valid value of `Self` that no
/// invariant of `Self` excludes, not even one that only safe code relies on (like a length that
/// must not exceed a capacity, or one that `#[trivial_type(validate = path)]` checks), so bytes of
/// `Self` never need to be checked. If `Self` implements [`TrivialType`], both flavours of its
/// parsing step `parse_step::<ALIGNED>()` accept every such pattern.
#[diagnostic::on_unimplemented(message = "`{Self}` doesn't accept every bit pattern")]
pub unsafe trait AnyBitPatternMarker {}

/// [`TrivialType`] whose every bit pattern is a valid value.
///
/// Implemented for every type that implements [`TrivialType`] and [`AnyBitPatternMarker`].
#[diagnostic::on_unimplemented(message = "`{Self}` doesn't accept every bit pattern")]
pub trait AnyBitPattern
where
    Self: TrivialType + AnyBitPatternMarker,
{
}

// Without this attribute errors report the unsatisfied `AnyBitPatternMarker` bound instead,
// suggesting to require the marker or to implement the `unsafe` marker manually
#[diagnostic::do_not_recommend]
impl<T> AnyBitPattern for T where T: TrivialType + AnyBitPatternMarker {}

/// Parsing step of a type whose every bit pattern is a valid value
#[inline(always)]
fn try_from_bytes_any_bit_pattern<T>(bytes: &[u8]) -> Option<(&Unaligned<T>, &[u8])>
where
    T: TrivialType + AnyBitPatternMarker,
{
    let (bytes, remainder) = bytes.split_at_checked(size_of::<T>())?;
    // SAFETY: `Unaligned<T>` has alignment 1 and the size of `T`, `bytes` are that many
    // initialized bytes, and any of them are a valid value of `T` (`AnyBitPatternMarker`)
    let value = unsafe { bytes.as_ptr().cast::<Unaligned<T>>().as_ref_unchecked() };
    Some((value, remainder))
}

/// Returns the bytes after `count` valid values of `T` at the beginning of `bytes`.
///
/// # Safety
/// If `ALIGNED`, `bytes` are aligned for `T`.
#[inline(always)]
pub(crate) unsafe fn try_skip_valid<T, const ALIGNED: bool>(
    bytes: &[u8],
    count: usize,
) -> Option<&[u8]>
where
    T: TrivialType,
{
    // Zero-sized values have no bytes, so only a check like a `validate` hook can reject one, and
    // it rejects either all of them or none, so one check replaces `count` steps that don't consume
    // bytes
    if size_of::<T>() == 0 {
        if count > 0 {
            // SAFETY: If `ALIGNED`, `bytes` are aligned for `T` (function contract)
            unsafe { T::parse_step::<ALIGNED>(bytes) }?;
        }
        return Some(bytes);
    }
    // With all elements split off first, every step gets exactly the bytes of one element, so for
    // types whose step only checks the length the loop is optimized away
    let (elements, remainder) = bytes.split_at_checked(count.checked_mul(size_of::<T>())?)?;
    for element in elements.as_chunks::<{ SIZE_OF::<T> }>().0 {
        // SAFETY: If `ALIGNED`, `bytes` are aligned for `T` (function contract), and each element
        // is at an offset into them that is a multiple of the size of `T`, and so of its alignment
        unsafe { T::parse_step::<ALIGNED>(element) }?;
    }
    Some(remainder)
}

// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for () {
    const ALIGNMENT: Alignment = Alignment::from_power(0)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::Unit as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Zero-sized, its only value has no bytes, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for () {}
// SAFETY: One byte, the parsing step accepts only `0` and `1`, the valid values of `bool`
unsafe impl TrivialType for bool {
    const ALIGNMENT: Alignment = Alignment::from_power(0)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::Bool as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        let (&[0 | 1], remainder) = bytes.split_first_chunk::<1>()? else {
            return None;
        };
        // SAFETY: `Unaligned<bool>` is one byte with alignment 1, the first byte is `0` or `1`
        let value = unsafe { bytes.as_ptr().cast::<Unaligned<Self>>().as_ref_unchecked() };
        Some((value, remainder))
    }
}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for u8 {
    const ALIGNMENT: Alignment = Alignment::from_power(0)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::U8 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for u8 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for u16 {
    const ALIGNMENT: Alignment = Alignment::from_power(1)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::U16 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for u16 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for u32 {
    const ALIGNMENT: Alignment = Alignment::from_power(2)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::U32 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for u32 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for u64 {
    const ALIGNMENT: Alignment = Alignment::from_power(3)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::U64 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for u64 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for u128 {
    // `Alignment::MAX` because native alignment for `u128` is 8 bytes (instead of 16) on 32-bit
    // platforms
    const ALIGNMENT: Alignment = Alignment::MAX;
    const METADATA: &[u8] = &[IoTypeMetadataKind::U128 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for u128 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for i8 {
    const ALIGNMENT: Alignment = Alignment::from_power(0)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::I8 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for i8 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for i16 {
    const ALIGNMENT: Alignment = Alignment::from_power(1)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::I16 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for i16 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for i32 {
    const ALIGNMENT: Alignment = Alignment::from_power(2)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::I32 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for i32 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for i64 {
    const ALIGNMENT: Alignment = Alignment::from_power(3)
        .expect("Alignment of a primitive type is larger than `Alignment::MAX`");
    const METADATA: &[u8] = &[IoTypeMetadataKind::I64 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for i64 {}
// SAFETY: Any bit pattern is valid, so it is safe to implement `TrivialType` for this type
unsafe impl TrivialType for i128 {
    // `Alignment::MAX` because native alignment for `i128` is 8 bytes (instead of 16) on 32-bit
    // platforms
    const ALIGNMENT: Alignment = Alignment::MAX;
    const METADATA: &[u8] = &[IoTypeMetadataKind::I128 as u8];

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        try_from_bytes_any_bit_pattern(bytes)
    }
}
// SAFETY: Any bit pattern is a valid value of integers, the parsing step only checks the length
unsafe impl AnyBitPatternMarker for i128 {}

const fn array_metadata(size: u32, inner_metadata: &[u8]) -> ([u8; MAX_METADATA_CAPACITY], usize) {
    concat_metadata_sources(&[
        &[IoTypeMetadataKind::Array as u8],
        &size.to_le_bytes(),
        inner_metadata,
    ])
}

// TODO: Change `usize` to `u32` once it is possible:
//  https://github.com/rust-lang/rust/issues/156745
// SAFETY: Elements follow each other without padding and are `TrivialType`, the parsing step checks
// every element
unsafe impl<const SIZE: usize, T> TrivialType for [T; SIZE]
where
    T: TrivialType,
    [(); SUPPORTED_ARRAY::<T, SIZE>]:,
{
    const ALIGNMENT: Alignment = T::ALIGNMENT;
    // Casting `SIZE` to `u32` is lossless, which is checked by the `SUPPORTED_ARRAY` bound
    const METADATA: &[u8] = {
        // The reference extends the lifetime of metadata scratch to that of the constant
        let (metadata_scratch, metadata_size) = &array_metadata(SIZE as u32, T::METADATA);
        metadata_scratch.split_at(*metadata_size).0
    };

    #[inline(always)]
    unsafe fn parse_step<const ALIGNED: bool>(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])> {
        let (bytes, remainder) = bytes.split_at_checked(size_of::<Self>())?;
        // SAFETY: If `ALIGNED`, `bytes` are aligned for `Self` (function contract), which has the
        // alignment of `T`
        unsafe { try_skip_valid::<T, ALIGNED>(bytes, SIZE) }?;
        // SAFETY: Elements follow each other without padding and each of them is a valid value as
        // checked above, `Unaligned<Self>` has alignment 1 and the size of `Self`
        let value = unsafe { bytes.as_ptr().cast::<Unaligned<Self>>().as_ref_unchecked() };
        Some((value, remainder))
    }
}

// SAFETY: Elements follow each other without padding, any bit pattern of each is a valid value,
// which the parsing step of elements accepts. There is no array size limit here, `AnyBitPattern`
// requires `[T; N]: TrivialType`, which has it.
unsafe impl<const SIZE: usize, T> AnyBitPatternMarker for [T; SIZE] where T: AnyBitPatternMarker {}

// SAFETY: All `TrivialType` instances are valid for `IoType`
unsafe impl<T> IoType for T
where
    T: TrivialType,
{
    const METADATA: &[u8] = T::METADATA;

    type PointerType = T;

    type WithLifetime<'b> = T;

    type Reborrowed<'b> = &'b mut T;

    #[inline(always)]
    fn size(&self) -> u32 {
        T::SIZE
    }

    #[inline(always)]
    fn capacity(&self) -> u32 {
        self.size()
    }

    #[inline(always)]
    #[track_caller]
    unsafe fn set_size(&mut self, size: u32) {
        debug_assert_eq!(size, T::SIZE, "`set_size` called with invalid input");
    }

    #[inline(always)]
    #[track_caller]
    unsafe fn from_ptr<'a>(
        ptr: &'a NonNull<Self::PointerType>,
        size: &'a u32,
        capacity: u32,
    ) -> impl Deref<Target = Self::WithLifetime<'a>> + 'a {
        debug_assert!(ptr.is_aligned(), "Misaligned pointer");
        debug_assert_eq!(*size, T::SIZE, "Invalid size");
        debug_assert!(
            *size <= capacity,
            "Size {size} must not exceed capacity {capacity}"
        );

        // SAFETY: guaranteed by this function signature
        unsafe { ptr.as_ref() }
    }

    #[inline(always)]
    #[track_caller]
    unsafe fn from_mut_ptr<'a>(
        ptr: &'a mut NonNull<Self::PointerType>,
        _size: &'a mut u32,
        capacity: u32,
    ) -> impl DerefMut<Target = Self::WithLifetime<'a>> + 'a {
        debug_assert!(ptr.is_aligned(), "Misaligned pointer");
        debug_assert!(
            Self::SIZE <= capacity,
            "Size {} must not exceed capacity {capacity}",
            Self::SIZE
        );

        // SAFETY: guaranteed by this function signature
        unsafe { ptr.as_mut() }
    }

    #[inline(always)]
    #[track_caller]
    unsafe fn try_from_ptr<'a>(
        ptr: &'a NonNull<Self::PointerType>,
        size: &'a u32,
        capacity: u32,
    ) -> Option<impl Deref<Target = Self::WithLifetime<'a>> + 'a> {
        debug_assert!(ptr.is_aligned(), "Misaligned pointer");
        debug_assert_eq!(*size, T::SIZE, "Invalid size");
        debug_assert!(
            *size <= capacity,
            "Size {size} must not exceed capacity {capacity}"
        );
        // SAFETY: `ptr` is valid for reads of `size` bytes, which is the size of `T`, initialized
        // and not written to during the call (function contract)
        let bytes = unsafe { slice::from_raw_parts(ptr.as_ptr().cast::<u8>(), size_of::<T>()) };
        // SAFETY: `ptr` is aligned for `T` (function contract)
        unsafe { T::parse_step::<true>(bytes) }?;

        // SAFETY: `size` is the size of `T` and doesn't exceed `capacity`, `ptr` is aligned and the
        // memory is not written to while the returned value exists (function contract), and it
        // holds a valid value of `T` as checked above
        Some(unsafe { Self::from_ptr(ptr, size, capacity) })
    }

    #[inline(always)]
    #[track_caller]
    unsafe fn try_from_mut_ptr<'a>(
        ptr: &'a mut NonNull<Self::PointerType>,
        size: &'a mut u32,
        capacity: u32,
    ) -> Option<impl DerefMut<Target = Self::WithLifetime<'a>> + 'a> {
        debug_assert!(ptr.is_aligned(), "Misaligned pointer");
        debug_assert_eq!(*size, T::SIZE, "Invalid size");
        debug_assert!(
            *size <= capacity,
            "Size {size} must not exceed capacity {capacity}"
        );
        // SAFETY: `ptr` is valid for reads of `size` bytes, which is the size of `T`, initialized
        // and not accessed otherwise during the call (function contract), the slice is not used
        // after parsing
        let bytes = unsafe { slice::from_raw_parts(ptr.as_ptr().cast::<u8>(), size_of::<T>()) };
        // SAFETY: `ptr` is aligned for `T` (function contract)
        unsafe { T::parse_step::<true>(bytes) }?;

        // SAFETY: `size` is the size of `T` and doesn't exceed `capacity`, `ptr` is aligned and the
        // memory is not accessed otherwise while the returned value exists (function contract),
        // and it holds a valid value of `T` as checked above
        Some(unsafe { Self::from_mut_ptr(ptr, size, capacity) })
    }

    #[inline(always)]
    fn as_ptr(&self) -> NonNull<Self::PointerType> {
        NonNull::from_ref(self)
    }

    #[inline(always)]
    fn as_mut_ptr(&mut self) -> NonNull<Self::PointerType> {
        NonNull::from_mut(self)
    }

    #[inline(always)]
    fn reborrow_mut(&mut self) -> Self::Reborrowed<'_> {
        self
    }
}