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

use core::convert::Infallible;
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,
};

/// Denotes an interiour-immutable type.
///
/// Note that this trait will be removed in favour
/// of [`core::marker::Freeze`] when the latter is
/// stabilised.
///
/// # Safety
///
/// Only types without interiour-mutability may
/// implement this trait. Types with
/// interiour-mutable fields (e.g. by
/// [`UnsafeCell`]) may still implement this trait
/// *if* the mutable behaviour is never observed on
/// constant objects.
///
/// [`UnsafeCell`]: core::cell::UnsafeCell
pub unsafe trait Immutable {}

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

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

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

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

unsafe impl Immutable for f32 {}

unsafe impl Immutable for f64 {}

unsafe impl Immutable for i128 {}

unsafe impl Immutable for i16 {}

unsafe impl Immutable for i32 {}

unsafe impl Immutable for i64 {}

unsafe impl Immutable for i8 {}

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

unsafe impl Immutable for isize {}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// SAFETY: `NonNull<T>` is transparent to
// to `*mut T`.
unsafe impl<T: ?Sized> Immutable for NonNull<T> {}

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

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

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

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

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

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

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

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

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

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

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

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

// SAFETY: The descriminant must be interiour-im-
// mutable as well.
unsafe impl<T: Immutable> Immutable for Option<T> {}

// SORT: pointer
// SAFETY: Pointer metadata must be interiour-im-
// mutable as well.
unsafe impl<T: ?Sized> Immutable for *const T {}

// SORT: pointer
// SAFETY: Pointer metadata must be interiour-im-
// mutable as well.
unsafe impl<T: ?Sized> Immutable for *mut T {}

// SAFETY: The descriminant must be interiour-im-
// mutable as well.
unsafe impl<T, E> Immutable for Result<T, E>
where
	T: Immutable,
	E: Immutable,
{}

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

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

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

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

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

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

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

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

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

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

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

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

unsafe impl Immutable for u128 {}

unsafe impl Immutable for u16 {}

unsafe impl Immutable for u32 {}

unsafe impl Immutable for u64 {}

unsafe impl Immutable for u8 {}

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

unsafe impl Immutable for usize {}

unsafe impl<T: Immutable> Immutable for Saturating<T> {}

// SORT: slice
unsafe impl<T: Immutable> Immutable for [T] {}

// SAFETY: `str` is tranpsarent to `[u8]`.
unsafe impl Immutable for str {}

unsafe impl<T: Immutable> Immutable for Wrapping<T> {}