multitype 0.21.1

// Copyright 2025-2026 Gabriel Bjørnager Jensen.
//
// SPDX: MIT OR Apache-2.0

//! The [`Integral`] trait.

mod test;

use core::ops::{
	Add,
	AddAssign,
	BitAnd,
	BitAndAssign,
	BitOr,
	BitOrAssign,
	BitXor,
	BitXorAssign,
	Div,
	DivAssign,
	Mul,
	MulAssign,
	Not,
	Rem,
	RemAssign,
	Shl,
	ShlAssign,
	Shr,
	ShrAssign,
	Sub,
	SubAssign,
};
use multitype::{Signed, Unsigned};

/// Denotes an integral types.
///
/// These include:
/// * [`i8`]
/// * [`i16`]
/// * [`i32`]
/// * [`i64`]
/// * [`i128`]
/// * [`isize`]
/// * [`u8`]
/// * [`u16`]
/// * [`u32`]
/// * [`u64`]
/// * [`u128`]
/// * [`usize`]
///
/// # Safety
///
/// [`Signed`] and [`Unsigned`] must be compatible
/// so that one may losslessly transmute between the
/// two.
///
/// [`Signed`]: Self::Signed
/// [`Unsigned`]: Self::Unsigned
///
/// All items must behave to the same specifications
/// as the standard items.
pub unsafe trait Integral
where
	Self:
		Add<Output = Self>
		+ AddAssign
		+ BitAnd<Output = Self>
		+ BitAndAssign
		+ BitOr<Output = Self>
		+ BitOrAssign
		+ BitXor<Output = Self>
		+ BitXorAssign
		+ Copy
		+ Div<Output = Self>
		+ DivAssign
		+ Mul<Output = Self>
		+ MulAssign
		+ Not<Output = Self>
		+ Ord
		+ Rem<Output = Self>
		+ RemAssign
		+ Shl<Output = Self>
		+ ShlAssign
		+ Shr<Output = Self>
		+ ShrAssign
		+ Sub<Output = Self>
		+ SubAssign,
{
	/// The signed variant of this type.
	type Signed: Signed<Unsigned = Self::Unsigned>;

	/// The unsigned variant of this type.
	type Unsigned: Unsigned<Signed = Self::Signed>;

	/// See [`i32::BITS`].
	const BITS: u32;

	/// See [`i32::MAX`].
	const MAX: Self;

	/// See [`i32::MIN`].
	const MIN: Self;

	/// See [`i32::abs_diff`].
	#[must_use]
	fn abs_diff(self, rhs: Self) -> Self::Unsigned;

	/// See [`i32::checked_add`].
	#[must_use]
	fn checked_add(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_div`].
	#[must_use]
	fn checked_div(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_div_euclid`].
	#[must_use]
	fn checked_div_euclid(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_ilog`].
	#[must_use]
	fn checked_ilog(self, rhs: Self) -> Option<u32>;

	/// See [`i32::checked_ilog10`].
	#[must_use]
	fn checked_ilog10(self) -> Option<u32>;

	/// See [`i32::checked_ilog2`].
	#[must_use]
	fn checked_ilog2(self) -> Option<u32>;

	/// See [`i32::checked_mul`].
	#[must_use]
	fn checked_mul(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_neg`].
	#[must_use]
	fn checked_neg(self) -> Option<Self>;

	/// See [`i32::checked_pow`].
	#[must_use]
	fn checked_pow(self, rhs: u32) -> Option<Self>;

	/// See [`i32::checked_rem`].
	#[must_use]
	fn checked_rem(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_rem_euclid`].
	#[must_use]
	fn checked_rem_euclid(self, rhs: Self) -> Option<Self>;

	/// See [`i32::checked_shl`].
	#[must_use]
	fn checked_shl(self, rhs: u32) -> Option<Self>;

	/// See [`i32::checked_shr`].
	#[must_use]
	fn checked_shr(self, rhs: u32) -> Option<Self>;

	/// See [`i32::checked_sub`].
	#[must_use]
	fn checked_sub(self, rhs: Self) -> Option<Self>;

	/// See [`i32::count_ones`].
	#[must_use]
	fn count_ones(self) -> u32;

	/// See [`i32::count_zeros`].
	#[must_use]
	fn count_zeros(self) -> u32;

	/// See [`i32::div_euclid`].
	#[must_use]
	fn div_euclid(self, rhs: Self) -> Self;

	/// See [`i32::from_be`].
	#[must_use]
	fn from_be(value: Self) -> Self;

	/// See [`i32::from_le`].
	#[must_use]
	fn from_le(value: Self) -> Self;

	/// See [`i32::highest_one`].
	#[must_use]
	fn highest_one(self) -> Option<u32>;

	/// See [`i32::ilog`].
	#[must_use]
	fn ilog(self, rhs: Self) -> u32;

	/// See [`i32::ilog10`].
	#[must_use]
	fn ilog10(self) -> u32;

	/// See [`i32::ilog2`].
	#[must_use]
	fn ilog2(self) -> u32;

	/// See [`i32::isolate_highest_one`].
	#[must_use]
	fn isolate_highest_one(self) -> Self;

	/// See [`i32::isolate_lowest_one`].
	#[must_use]
	fn isolate_lowest_one(self) -> Self;

	/// See [`i32::isqrt`].
	#[must_use]
	fn isqrt(self) -> Self;

	/// See [`i32::leading_ones`].
	#[must_use]
	fn leading_ones(self) -> u32;

	/// See [`i32::leading_zeros`].
	#[must_use]
	fn leading_zeros(self) -> u32;

	/// See [`i32::lowest_one`].
	#[must_use]
	fn lowest_one(self) -> Option<u32>;

	/// See [`i32::midpoint`].
	#[must_use]
	fn midpoint(self, rhs: Self) -> Self;

	/// See [`i32::overflowing_add`].
	#[must_use]
	fn overflowing_add(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_div`].
	#[must_use]
	fn overflowing_div(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_div_euclid`].
	#[must_use]
	fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_mul`].
	#[must_use]
	fn overflowing_mul(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_neg`].
	#[must_use]
	fn overflowing_neg(self) -> (Self, bool);

	/// See [`i32::overflowing_pow`].
	#[must_use]
	fn overflowing_pow(self, rhs: u32) -> (Self, bool);

	/// See [`i32::overflowing_rem`].
	#[must_use]
	fn overflowing_rem(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_rem_euclid`].
	#[must_use]
	fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool);

	/// See [`i32::overflowing_shl`].
	#[must_use]
	fn overflowing_shl(self, rhs: u32) -> (Self, bool);

	/// See [`i32::overflowing_shr`].
	#[must_use]
	fn overflowing_shr(self, rhs: u32) -> (Self, bool);

	/// See [`i32::overflowing_sub`].
	#[must_use]
	fn overflowing_sub(self, rhs: Self) -> (Self, bool);

	/// See [`i32::pow`].
	#[must_use]
	fn pow(self, rhs: u32) -> Self;

	/// See [`i32::rem_euclid`].
	#[must_use]
	fn rem_euclid(self, rhs: Self) -> Self;

	/// See [`i32::reverse_bits`].
	#[must_use]
	fn reverse_bits(self) -> Self;

	/// See [`i32::rotate_left`].
	#[must_use]
	fn rotate_left(self, rhs: u32) -> Self;

	/// See [`i32::rotate_right`].
	#[must_use]
	fn rotate_right(self, rhs: u32) -> Self;

	/// See [`i32::saturating_add`].
	#[must_use]
	fn saturating_add(self, rhs: Self) -> Self;

	/// See [`i32::saturating_div`].
	#[must_use]
	fn saturating_div(self, rhs: Self) -> Self;

	/// See [`i32::saturating_mul`].
	#[must_use]
	fn saturating_mul(self, rhs: Self) -> Self;

	/// See [`i32::saturating_pow`].
	#[must_use]
	fn saturating_pow(self, rhs: u32) -> Self;

	/// See [`i32::saturating_sub`].
	#[must_use]
	fn saturating_sub(self, rhs: Self) -> Self;

	/// See [`i32::strict_add`].
	#[must_use]
	fn strict_add(self, rhs: Self) -> Self;

	/// See [`i32::strict_div`].
	#[must_use]
	fn strict_div(self, rhs: Self) -> Self;

	/// See [`i32::strict_div_euclid`].
	#[must_use]
	fn strict_div_euclid(self, rhs: Self) -> Self;

	/// See [`i32::strict_mul`].
	#[must_use]
	fn strict_mul(self, rhs: Self) -> Self;

	/// See [`i32::strict_neg`].
	#[must_use]
	fn strict_neg(self) -> Self;

	/// See [`i32::strict_pow`].
	#[must_use]
	fn strict_pow(self, rhs: u32) -> Self;

	/// See [`i32::strict_rem`].
	#[must_use]
	fn strict_rem(self, rhs: Self) -> Self;

	/// See [`i32::strict_rem_euclid`].
	#[must_use]
	fn strict_rem_euclid(self, rhs: Self) -> Self;

	/// See [`i32::strict_shl`].
	#[must_use]
	fn strict_shl(self, rhs: u32) -> Self;

	/// See [`i32::strict_shr`].
	#[must_use]
	fn strict_shr(self, rhs: u32) -> Self;

	/// See [`i32::strict_sub`].
	#[must_use]
	fn strict_sub(self, rhs: Self) -> Self;

	/// See [`i32::swap_bytes`].
	#[must_use]
	fn swap_bytes(self) -> Self;

	/// See [`i32::to_be`].
	#[must_use]
	fn to_be(self) -> Self;

	/// See [`i32::to_le`].
	#[must_use]
	fn to_le(self) -> Self;

	/// See [`i32::trailing_ones`].
	#[must_use]
	fn trailing_ones(self) -> u32;

	/// See [`i32::trailing_zeros`].
	#[must_use]
	fn trailing_zeros(self) -> u32;

	/// See [`i32::unbounded_shl`].
	#[must_use]
	fn unbounded_shl(self, rhs: u32) -> Self;

	/// See [`i32::unbounded_shr`].
	#[must_use]
	fn unbounded_shr(self, rhs: u32) -> Self;

	/// See [`i32::unchecked_add`].
	#[expect(clippy::missing_safety_doc)]
	#[must_use]
	unsafe fn unchecked_add(self, rhs: Self) -> Self;

	/// See [`i32::unchecked_mul`].
	#[expect(clippy::missing_safety_doc)]
	#[must_use]
	unsafe fn unchecked_mul(self, rhs: Self) -> Self;

	/// See [`i32::unchecked_shl`].
	#[expect(clippy::missing_safety_doc)]
	#[must_use]
	unsafe fn unchecked_shl(self, rhs: u32) -> Self;

	/// See [`i32::unchecked_shr`].
	#[expect(clippy::missing_safety_doc)]
	#[must_use]
	unsafe fn unchecked_shr(self, rhs: u32) -> Self;

	/// See [`i32::unchecked_sub`].
	#[expect(clippy::missing_safety_doc)]
	#[must_use]
	unsafe fn unchecked_sub(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_add`].
	#[must_use]
	fn wrapping_add(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_div`].
	#[must_use]
	fn wrapping_div(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_div_euclid`].
	#[must_use]
	fn wrapping_div_euclid(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_mul`].
	#[must_use]
	fn wrapping_mul(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_neg`].
	#[must_use]
	fn wrapping_neg(self) -> Self;

	/// See [`i32::wrapping_pow`].
	#[must_use]
	fn wrapping_pow(self, rhs: u32) -> Self;

	/// See [`i32::wrapping_rem`].
	#[must_use]
	fn wrapping_rem(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_rem_euclid`].
	#[must_use]
	fn wrapping_rem_euclid(self, rhs: Self) -> Self;

	/// See [`i32::wrapping_shl`].
	#[must_use]
	fn wrapping_shl(self, rhs: u32) -> Self;

	/// See [`i32::wrapping_shr`].
	#[must_use]
	fn wrapping_shr(self, rhs: u32) -> Self;

	/// See [`i32::wrapping_sub`].
	#[must_use]
	fn wrapping_sub(self, rhs: Self) -> Self;
}