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

mod test;

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_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 that is zeroable.
///
/// # Safety
///
/// Only types that may be constructed from
/// all-zeros may implement this trait.
///
/// The provided functions of this trait may not be
/// overriden.
pub unsafe trait Zeroable {
	/// Constructs a new object from all-zeros.
	///
	/// This function is similar to
	/// [`MaybeUninit::zeroed`] but -- in contrast --
	/// is always safe to use.
	#[inline]
	#[must_use]
	fn zeroed() -> Self
	where
		Self: Sized,
	{
		let mut this = MaybeUninit::<Self>::uninit();
		this.make_zeroed();

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

	/// Overwrites the object with all-zeros.
	///
	/// The provided object is considered initialised
	/// after a successful call to this method.
	///
	/// This operation may be desired if the object in
	/// question is a secret and needs to be destroyed.
	#[inline]
	fn make_zeroed(&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-zeros
		// representation is valid.
		unsafe { ptr.write_bytes(0b00000000, len) };
	}
}

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

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

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

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

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

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

// SAFETY: `AtomicI8` is transparent to `i8`.
#[cfg(target_has_atomic = "8")]
unsafe impl Zeroable 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> Zeroable for AtomicPtr<T> {}

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

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

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

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

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

// SAFETY: All-zeros corresponds to `false`.
unsafe impl Zeroable for bool {}

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

// SAFETY: All-zeros corresponds to `\0`.
unsafe impl Zeroable for char {}

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

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

unsafe impl Zeroable for f32 {}

unsafe impl Zeroable for f64 {}

unsafe impl Zeroable for i128 {}

unsafe impl Zeroable for i16 {}

unsafe impl Zeroable for i32 {}

unsafe impl Zeroable for i64 {}

unsafe impl Zeroable for i8 {}

unsafe impl Zeroable for isize {}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// SAFETY: `PhantomData<T>` is a ZST but still in-
// habited.
unsafe impl<T: ?Sized> Zeroable for PhantomData<T> {}

// SAFETY: `PhantomPinned` is a ZST but still in-
// habited.
unsafe impl Zeroable for PhantomPinned {}

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

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

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

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

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

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1> Zeroable for (T0, T1)
where
	T0: Zeroable,
	T1: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2> Zeroable for (T0, T1, T2)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3> Zeroable for (T0, T1, T2, T3)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4> Zeroable for (T0, T1, T2, T3, T4)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5> Zeroable for (T0, T1, T2, T3, T4, T5)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
	T5: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6> Zeroable for (T0, T1, T2, T3, T4, T5, T6)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
	T5: Zeroable,
	T6: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6, T7> Zeroable for (T0, T1, T2, T3, T4, T5, T6, T7)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
	T5: Zeroable,
	T6: Zeroable,
	T7: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6, T7, T8> Zeroable for (T0, T1, T2, T3, T4, T5, T6, T7, T8)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
	T5: Zeroable,
	T6: Zeroable,
	T7: Zeroable,
	T8: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6, T7, T8, T9> Zeroable for (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9)
where
	T0: Zeroable,
	T1: Zeroable,
	T2: Zeroable,
	T3: Zeroable,
	T4: Zeroable,
	T5: Zeroable,
	T6: Zeroable,
	T7: Zeroable,
	T8: Zeroable,
	T9: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10> Zeroable for (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10)
where
	T0:  Zeroable,
	T1:  Zeroable,
	T2:  Zeroable,
	T3:  Zeroable,
	T4:  Zeroable,
	T5:  Zeroable,
	T6:  Zeroable,
	T7:  Zeroable,
	T8:  Zeroable,
	T9:  Zeroable,
	T10: Zeroable,
{}

// SORT: tuple
#[doc(hidden)]
unsafe impl<T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11> Zeroable for (T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11)
where
	T0:  Zeroable,
	T1:  Zeroable,
	T2:  Zeroable,
	T3:  Zeroable,
	T4:  Zeroable,
	T5:  Zeroable,
	T6:  Zeroable,
	T7:  Zeroable,
	T8:  Zeroable,
	T9:  Zeroable,
	T10: Zeroable,
	T11: Zeroable,
{}

unsafe impl Zeroable for u128 {}

unsafe impl Zeroable for u16 {}

unsafe impl Zeroable for u32 {}

unsafe impl Zeroable for u64 {}

unsafe impl Zeroable for u8 {}

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

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

unsafe impl Zeroable for usize {}

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

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

// SAFETY: Each zero corresponds to a UTF-8-encoded
// `\0`.
unsafe impl Zeroable for str {}