oct 0.24.0

// Copyright 2024-2025 Gabriel Bjørnager Jensen.
//
// This Source Code Form is subject to the terms of
// the Mozilla Public License, v. 2.0. If a copy of
// the MPL was not distributed with this file, you
// can obtain one at:
// <https://mozilla.org/MPL/2.0/>.

//! The [`IntoOcts`] trait.

mod test;

use crate::{Immutable, FromOcts};

use core::cell::{Cell, UnsafeCell};
use core::cmp::Reverse;
use core::convert::Infallible;
use core::marker::{PhantomData, PhantomPinned};
use core::mem::ManuallyDrop;
use core::ptr::NonNull;
use core::num::{NonZero, Saturating, Wrapping};
use core::slice;

#[cfg(target_arch = "x86")]
use core::arch::x86::{
	__m128,
	__m128bh,
	__m128d,
	__m128i,
	__m256,
	__m256bh,
	__m256d,
	__m256i,
	__m512,
	__m512bh,
	__m512d,
	__m512i,
};

#[cfg(target_arch = "x86_64")]
use core::arch::x86_64::{
	__m128,
	__m128bh,
	__m128d,
	__m128i,
	__m256,
	__m256bh,
	__m256d,
	__m256i,
	__m512,
	__m512bh,
	__m512d,
	__m512i,
};

#[cfg(target_has_atomic = "8")]
use core::sync::atomic::{AtomicBool, AtomicI8, AtomicU8};

#[cfg(target_has_atomic = "16")]
use core::sync::atomic::{AtomicI16, AtomicU16};

#[cfg(target_has_atomic = "32")]
use core::sync::atomic::{AtomicI32, AtomicU32};

#[cfg(target_has_atomic = "64")]
use core::sync::atomic::{AtomicI64, AtomicU64};

#[cfg(target_has_atomic = "128")]
use core::sync::atomic::{AtomicI128, AtomicU128};

#[cfg(target_has_atomic = "ptr")]
use core::sync::atomic::AtomicPtr;

/// Denotes a type representable as octets.
///
/// # Safety
///
/// All types that implement this trait must be
/// representable as arrays of [`u8`] objects. This,
/// most importantly, requires that the type in
/// question does not support being in an
/// uninitialised state (e.g. via padding bytes or
/// [`MaybeUninit`] fields).
///
/// [`MaybeUninit`]: core::mem::MaybeUninit
///
/// The provided functions of this trait may not be
/// overriden.
pub unsafe trait IntoOcts {
	/// Reinterprets the object as a slice of octets.
	#[inline(always)]
	#[must_use]
	fn as_octs(&self) -> &[u8]
	where
		Self: Immutable,
	{
		let len = size_of_val(self);
		let ptr = &raw const *self as *const u8;

		// SAFETY: Implementor guarantees initialised data.
		// `size_of_val` guarantees the exact size of the
		// referenced object. Additionally, `Immutable`
		// guarantees interiour-immutability.
		unsafe { slice::from_raw_parts(ptr, len) }
	}

	/// Reinterprets the object as a mutable slice of
	/// octets.
	#[inline(always)]
	#[must_use]
	fn as_octs_mut(&mut self) -> &mut [u8]
	where
		Self: FromOcts,
	{
		let len = size_of_val(self);
		let ptr = &raw mut *self as *mut u8;

		// SAFETY: Implementor guarantees initialised data.
		// `size_of_val` guarantees the exact size of the
		// referenced object. Lastly, `FromOcts` guarantees
		// that any write to the returned slice is valid.
		unsafe { slice::from_raw_parts_mut(ptr, len) }
	}
}

// SORT: array
// SAFETY: Arrays do not induce padding.
unsafe impl<T: IntoOcts, const N: usize> IntoOcts for [T; N] {}

// SAFETY: `AtomicBool` is transparent to `bool`.
#[cfg(target_has_atomic = "8")]
unsafe impl IntoOcts for AtomicBool {}

// SAFETY: `AtomicI128` is transparent to `i128`.
#[cfg(target_has_atomic = "128")]
unsafe impl IntoOcts for AtomicI128 {}

// SAFETY: `AtomicI16` is transparent to `i16`.
#[cfg(target_has_atomic = "16")]
unsafe impl IntoOcts for AtomicI16 {}

// SAFETY: `AtomicI32` is transparent to `i32`.
#[cfg(target_has_atomic = "32")]
unsafe impl IntoOcts for AtomicI32 {}

// SAFETY: `AtomicI64` is transparent to `i64`.
#[cfg(target_has_atomic = "64")]
unsafe impl IntoOcts for AtomicI64 {}

// SAFETY: `AtomicI8` is transparent to `i8`.
#[cfg(target_has_atomic = "8")]
unsafe impl IntoOcts for AtomicI8 {}

// FIXME: Require `T: Thin` instead of `T: Sized`.
// SAFETY: `AtomicPtr<T>` is transparent to
// `usize` when `T: Sized`.
#[cfg(target_has_atomic = "ptr")]
unsafe impl<T> IntoOcts for AtomicPtr<T> {}

// SAFETY: `AtomicU128` is transparent to `u128`.
#[cfg(target_has_atomic = "128")]
unsafe impl IntoOcts for AtomicU128 {}

// SAFETY: `AtomicU16` is transparent to `u16`.
#[cfg(target_has_atomic = "16")]
unsafe impl IntoOcts for AtomicU16 {}

// SAFETY: `AtomicU32` is transparent to `u32`.
#[cfg(target_has_atomic = "32")]
unsafe impl IntoOcts for AtomicU32 {}

// SAFETY: `AtomicU64` is transparent to `u64`.
#[cfg(target_has_atomic = "64")]
unsafe impl IntoOcts for AtomicU64 {}

// SAFETY: `AtomicU8` is transparent to `u8`.
#[cfg(target_has_atomic = "8")]
unsafe impl IntoOcts for AtomicU8 {}

unsafe impl IntoOcts for bool {}

// SAFETY: `Cell<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for Cell<T> {}

unsafe impl IntoOcts for char {}

#[cfg(feature = "f128")]
unsafe impl IntoOcts for f128 {}

#[cfg(feature = "f16")]
unsafe impl IntoOcts for f16 {}

unsafe impl IntoOcts for f32 {}

unsafe impl IntoOcts for f64 {}

unsafe impl IntoOcts for i128 {}

unsafe impl IntoOcts for i16 {}

unsafe impl IntoOcts for i32 {}

unsafe impl IntoOcts for i64 {}

unsafe impl IntoOcts for i8 {}

// SAFETY: `Infallible` cannot be constructed.
unsafe impl IntoOcts for Infallible {}

unsafe impl IntoOcts for isize {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m128 {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m128 {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m128bh {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m128bh {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m128d {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m128d {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m128i {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m128i {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m256 {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m256 {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m256bh {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m256bh {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m256d {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m256d {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m256i {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m256i {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m512 {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m512 {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m512bh {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m512bh {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m512d {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m512d {}

#[cfg(target_arch = "x86")]
unsafe impl IntoOcts for __m512i {}

#[cfg(target_arch = "x86_64")]
unsafe impl IntoOcts for __m512i {}

// SAFETY: `ManuallyDrop<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for ManuallyDrop<T> {}

// // SORT: never
// unsafe impl IntoOcts for ! {}

// SAFETY: `NonZero<i128>` is transparent to `i128`.
unsafe impl IntoOcts for NonZero<i128> {}

// SAFETY: `NonZero<i16>` is transparent to `i16`.
unsafe impl IntoOcts for NonZero<i16> {}

// SAFETY: `NonZero<i32>` is transparent to `i32`.
unsafe impl IntoOcts for NonZero<i32> {}

// SAFETY: `NonZero<i64>` is transparent to `i64`.
unsafe impl IntoOcts for NonZero<i64> {}

// SAFETY: `NonZero<i8>` is transparent to `i8`.
unsafe impl IntoOcts for NonZero<i8> {}

// SAFETY: `NonZero<isize>` is transparent to `isize`.
unsafe impl IntoOcts for NonZero<isize> {}

// SAFETY: `NonZero<u128>` is transparent to `u128`.
unsafe impl IntoOcts for NonZero<u128> {}

// SAFETY: `NonZero<u16>` is transparent to `u16`.
unsafe impl IntoOcts for NonZero<u16> {}

// SAFETY: `NonZero<u32>` is transparent to `u32`.
unsafe impl IntoOcts for NonZero<u32> {}

// SAFETY: `NonZero<u64>` is transparent to `u64`.
unsafe impl IntoOcts for NonZero<u64> {}

// SAFETY: `NonZero<u8>` is transparent to `u8`.
unsafe impl IntoOcts for NonZero<u8> {}

// SAFETY: `NonZero<usize>` is transparent to `usize`.
unsafe impl IntoOcts for NonZero<usize> {}

// FIXME: Require `T: Thin` instead of `T: Sized`.
// SAFETY: `Option<NonNull<T>>` is transparent to
// to `Option<NonZero<usize>>` when `T: Sized`.
unsafe impl<T> IntoOcts for Option<NonNull<T>> {}

// SAFETY: `Option<NonZero<i128>>` is transparent
// to `i128`.
unsafe impl IntoOcts for Option<NonZero<i128>> {}

// SAFETY: `Option<NonZero<i16>>` is transparent to
// `i16`.
unsafe impl IntoOcts for Option<NonZero<i16>> {}

// SAFETY: `Option<NonZero<i32>>` is transparent to
// `i32`.
unsafe impl IntoOcts for Option<NonZero<i32>> {}

// SAFETY: `Option<NonZero<i64>>` is transparent to
// `i64`.
unsafe impl IntoOcts for Option<NonZero<i64>> {}

// SAFETY: `Option<NonZero<i8>>` is transparent to
// `i8`.
unsafe impl IntoOcts for Option<NonZero<i8>> {}

// SAFETY: `Option<NonZero<isize>>` is transparent
// to `isize`.
unsafe impl IntoOcts for Option<NonZero<isize>> {}

// SAFETY: `Option<NonZero<u128>>` is transparent
// to `u128`.
unsafe impl IntoOcts for Option<NonZero<u128>> {}

// SAFETY: `Option<NonZero<u16>>` is transparent to
// `u16`.
unsafe impl IntoOcts for Option<NonZero<u16>> {}

// SAFETY: `Option<NonZero<u32>>` is transparent to
// `u32`.
unsafe impl IntoOcts for Option<NonZero<u32>> {}

// SAFETY: `Option<NonZero<u64>>` is transparent to
// `u64`.
unsafe impl IntoOcts for Option<NonZero<u64>> {}

// SAFETY: `Option<NonZero<u8>>` is transparent to
// `u8`.
unsafe impl IntoOcts for Option<NonZero<u8>> {}

// SAFETY: `Option<NonZero<usize>>` is transparent
// to `usize`.
unsafe impl IntoOcts for Option<NonZero<usize>> {}

// SAFETY: `PhantomData<T>` is a ZST.
unsafe impl<T: ?Sized> IntoOcts for PhantomData<T> {}

// SAFETY: `PhantomPinned` is a ZST.
unsafe impl IntoOcts for PhantomPinned {}

// SORT: pointer
// FIXME: Require `T: Thin` instead of `T: Sized`.
// SAFETY: `*const T` is transparent to `usize`
// when `T: Sized`.
unsafe impl<T> IntoOcts for *const T {}

// SORT: pointer
// FIXME: Require `T: Thin` instead of `T: Sized`.
// SAFETY: `*mut T` is transparent to `usize`
// when `T: Sized`.
unsafe impl<T> IntoOcts for *mut T {}

// SAFETY `Reverse<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for Reverse<T> {}

// SAFETY: `Saturating<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for Saturating<T> {}

// SORT: slice
// SAFETY: Slices have the same representation as
// arrays.
unsafe impl<T: IntoOcts> IntoOcts for [T] {}

unsafe impl IntoOcts for str {}

// SORT: tuple
/// Implemented for tuples with up to twelve
/// members.
#[cfg_attr(feature = "unstable_docs", doc(fake_variadic))]
unsafe impl<T: IntoOcts> IntoOcts for (T,) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T, T, T, T, T) {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
#[doc(hidden)]
unsafe impl<T: IntoOcts> IntoOcts for (T, T, T, T, T, T, T, T, T, T, T, T) {}

unsafe impl IntoOcts for u128 {}

unsafe impl IntoOcts for u16 {}

unsafe impl IntoOcts for u32 {}

unsafe impl IntoOcts for u64 {}

unsafe impl IntoOcts for u8 {}

// SORT: unit
unsafe impl IntoOcts for () {}

// SAFETY: `UnsafeCell<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for UnsafeCell<T> {}

unsafe impl IntoOcts for usize {}

// SAFETY: `Wrapping<T>` is transparent to `T`.
unsafe impl<T: IntoOcts> IntoOcts for Wrapping<T> {}