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 [`FromOcts`] trait.

mod test;

use crate::{Immutable, Zeroable};

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

#[cfg(target_has_atomic = "8")]
use core::sync::atomic::{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_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,
};

/// Denotes a type that can represent all octets.
///
/// # Pointers
///
/// This type isn't implemented for pointers as any
/// pointer constructed from such octets would be
/// without provenance -- even if the address itself
/// is valid. We do therefore not implement this
/// trait for any pointer type as we see it to be
/// too confusing.
///
/// Pointers do, however, implement [`Zeroable`], as
/// such behaviour cannot be confused in the same
/// way. Similarly, pointers also implement
/// [`IntoOcts`] as that alone can't lead to any
/// undefined behaviour.
///
/// [`IntoOcts`]: crate::IntoOcts
///
/// Note that this decision may be overtuned in the
/// future.
///
/// # Safety
///
/// Types that implement this trait must be
/// represent from any permutation of [`u8`]
/// patterns. Furthermore, any such representation
/// must constitute an initialised state of the type
/// in question (by extension, this prohibits
/// uninhabited types from implementing this trait).
///
/// The provided functions of this trait may not be
/// overriden.
pub unsafe trait FromOcts: Zeroable {
	/// Reads and object from an object slice.
	///
	/// # Panics
	///
	/// If the length of the provided octets is not
	/// exactly equal to the size of `Self`, this
	/// constructor will panic.
	#[inline(always)]
	#[must_use]
	#[track_caller]
	fn read_from_octs(octs: &[u8]) -> Self
	where
		Self: Sized,
	{
		// NOTE: Octets may be unaligned.

		// SAFETY: Implementors guarantee that we may rein-
		// terpret such octets as the implementing object,
		// which implies that object being initialised. We
		// have asserted that the octets are of a suffi-
		// cient size.
		let p = octs.as_ptr() as *const Self;

		// SAFETY: The pointer is derived from a reference.
		// We make sure to use an unaligned read.
		unsafe { p.read_unaligned() }
	}

	/// Attempts to construct a constant reference from
	/// an octet slice.
	///
	/// # Panics
	///
	/// If the length of the provided octets is not
	/// exactly equal to the size of `Self` or the
	/// octets themselves are unaligned, this
	/// constructor will panic.
	#[inline]
	#[must_use]
	#[track_caller]
	fn ref_from_octs(octs: &[u8]) -> &Self
	where
		Self: Sized + Immutable,
	{
		assert_eq!(
			octs.len(),
			size_of::<Self>(),
			"cannot construct reference from inexactly-sized octets",
		);

		// SAFETY: Implementors guarantee that we may rein-
		// terpret such octets as the implementing type.
		let p = octs.as_ptr() as *const Self;

		assert!(
			p.is_aligned(),
			"cannot construct reference from unaligned octets",
		);

		// SAFETY: We have tested that the octets are both
		// sized properly and aligned. `Immutable` guaran-
		// tees that the returned reference cannot be used
		// to modify the original octets.
		unsafe { &*p }
	}

	/// Attempts to construct a mutable reference from
	/// an octet slice.
	///
	/// # Panics
	///
	/// If the length of the provided octets is not
	/// exactly equal to the size of `Self` or the
	/// octets themselves are unaligned, this
	/// constructor will panic.
	#[inline]
	#[must_use]
	#[track_caller]
	fn mut_from_octs(octs: &mut [u8]) -> &mut Self
	where
		Self: Sized,
	{
		// NOTE: No need to require `Immutable` as writes
		// are always allowed.

		assert_eq!(
			octs.len(),
			size_of::<Self>(),
			"cannot construct reference from inexactly-sized octets",
		);

		// SAFETY: Implementors guarantee that we may rein-
		// terpret such octets as the implementing type. We
		// have tested that the octets are both sized prop-
		// erly and aligned.
		let p = octs.as_mut_ptr() as *mut Self;

		assert!(
			p.is_aligned(),
			"cannot construct reference from unaligned octets",
		);

		// SAFETY: We have tested that the octets are both
		// sized properly and aligned. Furthermore, given
		// that it derives from a mutable reference, we can
		// guarantee that it is also exclusive.
		unsafe { &mut *p }
	}

	/// Constructs a new object from all-ones.
	#[inline]
	#[must_use]
	fn oned() -> Self
	where
		Self: Sized,
	{
		let mut this = MaybeUninit::<Self>::uninit();
		this.make_oned();

		// SAFETY: `make_oned` guarantees an initialised
		// state.
		unsafe { this.assume_init() }
	}

	/// Overwrites the object with all-ones.
	///
	/// The provided object is considered initialised
	/// after a successful call to this method.
	#[inline]
	fn make_oned(&mut self) {
		let len = size_of_val(self);
		let ptr = &raw mut *self as *mut u8;

		// SAFETY `size_of_val` guarantees the exact size
		// of the referenced object. Implementing this
		// trait additionally guarantees that an all-ones
		// representation is valid.
		unsafe { ptr.write_bytes(0b11111111, len) };
	}
}

// SORT: array
unsafe impl<T: FromOcts, const N: usize> FromOcts for [T; N] {}

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

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

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

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

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

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

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

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

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

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

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

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

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

unsafe impl FromOcts for f32 {}

unsafe impl FromOcts for f64 {}

unsafe impl FromOcts for i128 {}

unsafe impl FromOcts for i16 {}

unsafe impl FromOcts for i32 {}

unsafe impl FromOcts for i64 {}

unsafe impl FromOcts for i8 {}

unsafe impl FromOcts for isize {}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// 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> FromOcts for Option<NonNull<T>> {}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

unsafe impl FromOcts for str {}

// SORT: tuple
// SAFETY: Homogeneous tuples have the same repre-
// sentation as arrays.
/// Implemented for tuples with up to twelve
/// members.
#[cfg_attr(feature = "unstable_docs", doc(fake_variadic))]
unsafe impl<T: FromOcts> FromOcts for (T,) {}

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

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

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

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

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

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

unsafe impl FromOcts for u128 {}

unsafe impl FromOcts for u16 {}

unsafe impl FromOcts for u32 {}

unsafe impl FromOcts for u64 {}

unsafe impl FromOcts for u8 {}

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

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

unsafe impl FromOcts for usize {}

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