num_valid/core/traits/

raw.rs

#![deny(rustdoc::broken_intra_doc_links)]

//! Raw trait definitions for unchecked scalar operations.
//!
//! This module defines the fundamental traits for raw number types (like `f64` or `rug::Float`).
//! These traits provide `unchecked_*` methods that assume inputs are valid and do not perform
//! any validation.
//!
//! # Trait Hierarchy
//!
//! ```text
//! RawScalarTrigonometric ─┐
//! RawScalarHyperbolic ────┼──> RawScalarTrait ──> RawRealTrait
//! RawScalarPow ───────────┘                   └──> RawComplexTrait
//! ```

use crate::{
    Arithmetic, Conjugate, NeumaierAddable, ScalarCore,
    core::{
        errors::{
            ErrorsRawRealToInteger, ErrorsValidationRawComplex, ErrorsValidationRawReal,
            RawRealConversionError, capture_backtrace,
        },
        traits::validation::{FpChecks, sealed::NativeReal},
    },
    functions::{Rounding, Sign},
    kernels::PrecisionBits,
};

#[cfg(feature = "rug")]
use duplicate::duplicate_item;

use std::{
    cmp::Ordering,
    hash::Hasher,
    num::FpCategory,
    ops::{Mul, MulAssign},
};
//use try_create::IntoInner;

// =============================================================================
// Trigonometric Operations
// =============================================================================

/// Trait for unchecked trigonometric operations.
///
/// Provides sine, cosine, tangent and their inverse functions without validation.
pub trait RawScalarTrigonometric {
    /// Computes the sine without validation.
    fn unchecked_sin(self) -> Self;

    /// Computes the arcsine without validation.
    fn unchecked_asin(self) -> Self;

    /// Computes the cosine without validation.
    fn unchecked_cos(self) -> Self;

    /// Computes the arccosine without validation.
    fn unchecked_acos(self) -> Self;

    /// Computes the tangent without validation.
    fn unchecked_tan(self) -> Self;

    /// Computes the arctangent without validation.
    fn unchecked_atan(self) -> Self;
}

// =============================================================================
// Hyperbolic Operations
// =============================================================================

/// Trait for unchecked hyperbolic operations.
///
/// Provides hyperbolic sine, cosine, tangent and their inverse functions without validation.
pub trait RawScalarHyperbolic {
    /// Computes the hyperbolic sine without validation.
    fn unchecked_sinh(self) -> Self;

    /// Computes the inverse hyperbolic sine without validation.
    fn unchecked_asinh(self) -> Self;

    /// Computes the hyperbolic cosine without validation.
    fn unchecked_cosh(self) -> Self;

    /// Computes the inverse hyperbolic cosine without validation.
    fn unchecked_acosh(self) -> Self;

    /// Computes the hyperbolic tangent without validation.
    fn unchecked_tanh(self) -> Self;

    /// Computes the inverse hyperbolic tangent without validation.
    fn unchecked_atanh(self) -> Self;
}

// =============================================================================
// Power Operations
// =============================================================================

/// Trait for unchecked power operations with integer exponents.
///
/// Provides power functions for all standard integer types without validation.
pub trait RawScalarPow {
    /// Raises `self` to the power of an `i8` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid.
    fn unchecked_pow_exponent_i8(self, exponent: &i8) -> Self;

    /// Raises `self` to the power of an `i16` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid.
    fn unchecked_pow_exponent_i16(self, exponent: &i16) -> Self;

    /// Raises `self` to the power of an `i32` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid.
    fn unchecked_pow_exponent_i32(self, exponent: &i32) -> Self;

    /// Raises `self` to the power of an `i64` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_i64(self, exponent: &i64) -> Self;

    /// Raises `self` to the power of an `i128` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_i128(self, exponent: &i128) -> Self;

    /// Raises `self` to the power of an `isize` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_isize(self, exponent: &isize) -> Self;

    /// Raises `self` to the power of a `u8` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid.
    fn unchecked_pow_exponent_u8(self, exponent: &u8) -> Self;

    /// Raises `self` to the power of a `u16` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid.
    fn unchecked_pow_exponent_u16(self, exponent: &u16) -> Self;

    /// Raises `self` to the power of a `u32` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_u32(self, exponent: &u32) -> Self;

    /// Raises `self` to the power of a `u64` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_u64(self, exponent: &u64) -> Self;

    /// Raises `self` to the power of a `u128` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_u128(self, exponent: &u128) -> Self;

    /// Raises `self` to the power of a `usize` exponent without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid. For integer powers, this
    /// includes ensuring the `exponent` is within the representable range of the underlying
    /// power function (e.g., `i32` for `f64::powi`).
    fn unchecked_pow_exponent_usize(self, exponent: &usize) -> Self;
}

pub trait RawScalarValidate: Sized {
    type ValidationError: std::error::Error;

    #[inline(always)]
    fn validate_raw_scalar(self) -> Result<Self, Self::ValidationError> {
        self.validate_raw_scalar_ref().map(|_| self)
    }

    #[inline(always)]
    fn validate_in_debug_raw_scalar(self) -> Result<Self, Self::ValidationError> {
        self.validate_in_debug_raw_scalar_ref().map(|_| self)
    }

    #[inline(always)]
    fn validate_in_debug_raw_scalar_ref(&self) -> Result<(), Self::ValidationError> {
        #[cfg(debug_assertions)]
        {
            self.validate_raw_scalar_ref()
        }
        #[cfg(not(debug_assertions))]
        {
            Ok(())
        }
    }

    fn validate_raw_scalar_ref(&self) -> Result<(), Self::ValidationError>;
}

// =============================================================================
// Core Scalar Trait
// =============================================================================

/// A baseline trait for raw scalar types, defining core operations and properties.
///
/// This trait must be implemented by the underlying number types used in a kernel,
/// such as like [`f64`] or [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html).
/// It provides a standard interface for arithmetic
/// and a suite of `unchecked_*` methods for mathematical functions.
///
/// ## Hashing Support
///
/// All raw scalar types (both real and complex) must implement [`compute_hash_raw_scalar()`](Self::compute_hash_raw_scalar),
/// which provides a consistent hashing mechanism. The hash implementation must ensure:
///
/// - **Mathematical Equality**: Values that are mathematically equal produce identical hashes
/// - **Signed Zero Handling**: Both `+0.0` and `-0.0` hash to the same value
/// - **Finite Values Only**: The hash is only well-defined for finite values (not NaN or infinity)
/// - **Consistency**: The same value always produces the same hash across multiple calls
///
/// For complex numbers, the hash is computed by sequentially hashing the real and imaginary
/// parts, ensuring that different complex numbers produce different hashes while maintaining
/// the equality invariant.
///
/// This enables validated wrapper types to implement [`Hash`](std::hash::Hash) when their validation
/// policies guarantee finite values (via [`crate::core::traits::validation::GuaranteesFiniteRealValues`]),
/// allowing them to be used as keys in [`HashMap`](std::collections::HashMap) and [`HashSet`](std::collections::HashSet).
///
/// # Safety and Contracts
///
/// The `unchecked_*` methods are designed for performance and assume that the caller
/// has already validated the inputs. Calling them with invalid data (e.g., `unchecked_sqrt`
/// on a negative real number) may lead to panics, incorrect results, or undefined behavior,
/// depending on the underlying type's implementation.
pub trait RawScalarTrait:
    ScalarCore
//    + IntoInner<InnerType = Self>
    + Arithmetic
    + NeumaierAddable
    + FpChecks
    + RawScalarTrigonometric
    + RawScalarHyperbolic
    + RawScalarPow
    + RawScalarValidate
{
    /// Returns `true` if `self` is zero.
    fn is_zero(&self) -> bool;

    /// Returns zero with the given precision.
    fn raw_zero(precision: u32) -> Self;

    /// Returns one with the given precision.
    fn raw_one(precision: u32) -> Self;

    /// Returns negative one with the given precision.
    #[inline(always)]
    fn raw_negative_one(precision: u32) -> Self {
        Self::raw_one(precision).neg()
    }

    /// Computes the reciprocal (1/x) without validation.
    ///
    /// **Contract:** The caller must ensure `self` is not zero.
    fn unchecked_reciprocal(self) -> Self;

    /// Computes the exponential (e^x) without validation.
    ///
    /// **Contract:** The caller must ensure the input is valid.
    fn unchecked_exp(self) -> Self;

    /// Computes the square root without validation.
    ///
    /// **Contract:** For real numbers, the caller must ensure `self >= 0`.
    fn unchecked_sqrt(self) -> Self;

    /// Computes the natural logarithm without validation.
    fn unchecked_ln(self) -> Self;

    /// Computes the base-2 logarithm without validation.
    fn unchecked_log2(self) -> Self;

    /// Computes the base-10 logarithm without validation.
    fn unchecked_log10(self) -> Self;

    /// Multiplies and adds in one fused operation, rounding to the nearest with only one rounding error.
    ///
    /// `a.mul_add(b, c)` produces a result like `a * &b + &c`.
    ///
    /// **Contract:** The caller must ensure all inputs are valid.
    fn unchecked_mul_add(self, b: &Self, c: &Self) -> Self;

    /// Computes a hash value for this scalar (real or complex).
    ///
    /// This method must ensure that mathematically equal values produce
    /// the same hash, even across different representations (e.g., +0.0 and -0.0).
    ///
    /// For complex numbers, implementations should hash the real and imaginary
    /// parts sequentially to ensure distinct complex numbers have different hashes.
    ///
    /// # Implementation Notes
    ///
    /// - For real numbers: Hash the value directly, normalizing signed zeros
    /// - For complex numbers: Call `compute_hash_raw_scalar()` on real part, then imaginary part
    ///
    /// # Debug Assertions
    ///
    /// Implementations should include a debug assertion that the value is finite,
    /// as hashing non-finite values may lead to inconsistent results.
    fn compute_hash_raw_scalar<H: Hasher>(&self, state: &mut H);
}

// =============================================================================
// Real Trait
// =============================================================================

/// A trait for raw real scalar types, extending [`RawScalarTrait`] with real-specific operations.
///
/// This trait defines the fundamental operations for real number types without
/// validation or safety checks. Implementations should assume inputs are valid
/// and focus on computational efficiency.
///
/// This trait is implemented by the underlying real number types within a kernel, such as [`f64`]
/// or [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html).
/// It builds upon [`RawScalarTrait`] by adding operations that are unique
/// to real numbers, like `atan2`, and by enforcing an ordering relationship.
///
/// ## Hashing Support
///
/// Types implementing this trait must provide a `compute_hash` method that:
/// - Produces consistent hash values for mathematically equal numbers
/// - Handles floating-point edge cases (like signed zeros) correctly  
/// - Maintains the contract that `a == b` implies `hash(a) == hash(b)`
///
/// This enables validated wrapper types to implement [`Hash`](std::hash::Hash) when appropriate
/// validation policies guarantee finite values.
///
/// # Trait Bounds
///
/// - `RawScalarTrait<ValidationError = ErrorsValidationRawReal<Self>>`: Ensures that the type
///   is a raw scalar and that its validation error type is the standard one for real numbers.
/// - [`PartialOrd`]: Requires that the type can be partially ordered, which is fundamental for
///   real numbers.
///
/// # Associated Types
///
/// - `type RawComplex: RawComplexTrait<RawReal = Self>`: This links the raw real type to its
///   corresponding complex number representation. For example, for [`f64`], this would be
///   [`num::Complex<f64>`]. This association is vital for operations that can transition
///   from the real to the complex domain.
pub trait RawRealTrait:
    RawScalarTrait<ValidationError = ErrorsValidationRawReal<Self>>
    + PartialOrd
    + Sign
    + Rounding
    + PrecisionBits
{
    /// The associated complex type that uses this type as its real part.
    type RawComplex: RawComplexTrait<RawReal = Self>;

    /// Computes the absolute value of `self` without validation.
    ///
    /// **Contract:** The caller must ensure that the input value has already been validated
    /// and is suitable for the operation.
    fn unchecked_abs(self) -> Self;

    /// Computes the four-quadrant arctangent of `self` (`y`) and `denominator` (`x`) without validation.
    ///
    /// **Contract:** The caller must ensure that `self` and `denominator` are not both zero.
    fn unchecked_atan2(self, denominator: &Self) -> Self;

    /// Raises `self` to the power of a real `exponent` without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid for the power function. For
    /// example, if `self` is negative, the `exponent` should be an integer, but this function
    /// does not enforce this.
    fn unchecked_pow_exponent_real(self, exponent: &Self) -> Self;

    /// Computes the Euclidean distance `sqrt(self² + other²)` without validation.
    fn unchecked_hypot(self, other: &Self) -> Self;

    /// Computes `ln(1 + self)` accurately for small values without validation.
    fn unchecked_ln_1p(self) -> Self;

    /// Computes `exp(self) - 1` accurately for small values without validation.
    fn unchecked_exp_m1(self) -> Self;

    /// Multiplies two pairs and adds them, rounding to the nearest.
    /// `a.unchecked_mul_add_mul_mut(&b, &c, &d)` produces a result like `&a * &b + &c * &d`, but stores the result in `a` using its precision.
    ///
    /// **Contract:** The caller must ensure all inputs are valid.
    fn unchecked_mul_add_mul_mut(&mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self);

    /// Multiplies two pairs and subtracts them, rounding to the nearest.
    /// `a.unchecked_mul_sub_mul_mut(&b, &c, &d)` produces a result like `&a * &b - &c * &d`, but stores the result in `a` using its precision.
    ///
    /// **Contract:** The caller must ensure all inputs are valid.
    fn unchecked_mul_sub_mul_mut(&mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self);

    /// Performs a total ordering comparison.
    fn raw_total_cmp(&self, other: &Self) -> Ordering;

    /// Clamps the value within the specified bounds.
    fn raw_clamp(self, min: &Self, max: &Self) -> Self;

    /// Classifies the floating-point value.
    fn raw_classify(&self) -> FpCategory;

    /// Returns two with the given precision.
    fn raw_two(precision: u32) -> Self;

    /// Returns 0.5 with the given precision.
    fn raw_one_div_2(precision: u32) -> Self;

    /// Returns π with the given precision.
    fn raw_pi(precision: u32) -> Self;

    /// Returns 2π with the given precision.
    fn raw_two_pi(precision: u32) -> Self;

    /// Returns π/2 with the given precision.
    fn raw_pi_div_2(precision: u32) -> Self;

    /// Returns the maximum finite value with the given precision.
    fn raw_max_finite(precision: u32) -> Self;

    /// Returns the minimum finite value with the given precision.
    fn raw_min_finite(precision: u32) -> Self;

    /// Returns the machine epsilon with the given precision.
    fn raw_epsilon(precision: u32) -> Self;

    /// Returns ln(2) with the given precision.
    fn raw_ln_2(precision: u32) -> Self;

    /// Returns ln(10) with the given precision.
    fn raw_ln_10(precision: u32) -> Self;

    /// Returns log₁₀(2) with the given precision.
    fn raw_log10_2(precision: u32) -> Self;

    /// Returns log₂(10) with the given precision.
    fn raw_log2_10(precision: u32) -> Self;

    /// Returns log₂(e) with the given precision.
    fn raw_log2_e(precision: u32) -> Self;

    /// Returns log₁₀(e) with the given precision.
    fn raw_log10_e(precision: u32) -> Self;

    /// Returns e (Euler's number) with the given precision.
    fn raw_e(precision: u32) -> Self;

    /// Safely converts the truncated value to `usize`.
    ///
    /// Truncates toward zero and validates the result is a valid `usize`.
    ///
    /// # Returns
    ///
    /// - `Ok(usize)`: If truncated value is in `0..=usize::MAX`
    /// - `Err(ErrorsRawRealToInteger)`: If value is not finite or out of range
    ///   - `NotFinite`: Value is `NaN` or `±∞`
    ///   - `OutOfRange`: Value is negative or > `usize::MAX`
    ///
    /// # Note
    ///
    /// The `NotAnInteger` error variant is not returned because truncation
    /// explicitly handles the fractional part.
    ///
    /// # Examples
    ///
    /// ```
    /// # use num_valid::core::traits::raw::RawRealTrait;
    /// let value = 42.9_f64;
    /// assert_eq!(value.truncate_to_usize().unwrap(), 42);
    ///
    /// let zero = 0.0_f64;
    /// assert_eq!(zero.truncate_to_usize().unwrap(), 0);
    /// ```
    ///
    /// ## Error cases
    ///
    /// ```
    /// # use num_valid::core::traits::raw::RawRealTrait;
    /// # use num_valid::core::errors::ErrorsRawRealToInteger;
    /// // Negative value
    /// let neg = -10.5_f64;
    /// assert!(matches!(neg.truncate_to_usize(), Err(ErrorsRawRealToInteger::OutOfRange { .. })));
    ///
    /// // Too large for usize
    /// let large = (usize::MAX as f64) + 100.0;
    /// assert!(matches!(large.truncate_to_usize(), Err(ErrorsRawRealToInteger::OutOfRange { .. })));
    ///
    /// // Not finite
    /// let nan = f64::NAN;
    /// assert!(matches!(nan.truncate_to_usize(), Err(ErrorsRawRealToInteger::NotFinite { .. })));
    /// ```
    fn truncate_to_usize(self) -> Result<usize, ErrorsRawRealToInteger<Self, usize>>;

    /// Converts `self` into another raw real type.
    ///
    /// The caller provides `precision_out`, which is interpreted by the target
    /// type `RawRealOut`:
    ///
    /// - fixed-precision targets (`f32`, `f64`) require exact mantissa widths
    ///   (24 and 53 respectively), otherwise
    ///   [`RawRealConversionError::InvalidOutputPrecision`] is returned;
    /// - variable-precision targets (e.g. `rug::Float`) use `precision_out` as
    ///   requested output precision.
    ///
    /// Implementations enforce exact representability via roundtrip checks and
    /// return [`RawRealConversionError::NonRepresentableExactly`] when needed.
    #[inline(always)]
    fn try_convert<RawRealOut>(
        self,
        precision_out: u32,
    ) -> Result<RawRealOut, RawRealConversionError<Self, RawRealOut>>
    where
        RawRealOut: RawRealTrait + TryConvertFromRawReal<Self>,
    {
        RawRealOut::try_convert_from_raw_real(self, precision_out)
    }
}

/// Conversion contract from one raw real type to another.
///
/// This trait is the low-level engine behind [`RawRealTrait::try_convert`].
/// Implementors define how to convert from `RawRealIn` into `Self`, including
/// precision handling and exact representability guarantees.
///
/// # Design
///
/// - `RawRealIn` is the input raw real type.
/// - `Self` is the output raw real type.
/// - `precision_out` is always interpreted by the output type (`Self`).
///
/// # Error Semantics
///
/// Implementations should map failures to [`RawRealConversionError`]:
/// - input validation failures -> `InputValidation`
/// - output validation failures -> `OutputValidation`
/// - invalid requested precision for fixed-precision targets -> `InvalidOutputPrecision`
/// - exactness loss after conversion -> `NonRepresentableExactly`
pub trait TryConvertFromRawReal<RawRealIn: RawRealTrait>: RawRealTrait {
    /// Performs raw-real conversion with explicit output precision.
    ///
    /// # Parameters
    ///
    /// - `value_in`: input raw value to be converted.
    /// - `precision_out`: requested output precision interpreted by `Self`.
    ///
    /// # Returns
    ///
    /// - `Ok(Self)` when conversion is valid and exact under the trait contract.
    /// - `Err(RawRealConversionError<RawRealIn, Self>)` otherwise.
    fn try_convert_from_raw_real(
        value_in: RawRealIn,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<RawRealIn, Self>>;
}

fn try_validity_precision_out<RealIn: RawRealTrait, RealOut: NativeReal>(
    value_in: &RealIn,
    precision_out: u32,
) -> Result<(), RawRealConversionError<RealIn, RealOut>> {
    if precision_out != RealOut::MANTISSA_DIGITS {
        return Err(RawRealConversionError::InvalidOutputPrecision {
            value_in: value_in.clone(),
            valid_precision_out: RealOut::MANTISSA_DIGITS,
            precision_out,
            backtrace: capture_backtrace(),
        });
    }
    Ok(())
}

#[inline(always)]
fn try_validate_input_value<RealIn: RawRealTrait, RealOut: RawRealTrait>(
    value_in: RealIn,
) -> Result<RealIn, RawRealConversionError<RealIn, RealOut>> {
    value_in
        .validate_raw_scalar()
        .map_err(|e| RawRealConversionError::InputValidation { source: e })
}

#[inline(always)]
fn try_validate_output_value<RealIn: RawRealTrait, RealOut: RawRealTrait>(
    value_out: RealOut,
) -> Result<RealOut, RawRealConversionError<RealIn, RealOut>> {
    value_out
        .validate_raw_scalar()
        .map_err(|e| RawRealConversionError::OutputValidation { source: e })
}

impl<T: NativeReal> TryConvertFromRawReal<T> for T {
    #[inline(always)]
    fn try_convert_from_raw_real(
        value: T,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<T, T>> {
        try_validity_precision_out::<T, T>(&value, precision_out)?;

        try_validate_input_value::<T, T>(value)
    }
}

impl TryConvertFromRawReal<f64> for f32 {
    fn try_convert_from_raw_real(
        value_in: f64,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<f64, f32>> {
        try_validity_precision_out::<f64, f32>(&value_in, precision_out)?;

        let value_in = try_validate_input_value::<f64, f32>(value_in)?;

        // convert to f32 and check if f32 can represent the value exactly
        let value_out = try_validate_output_value::<f64, f32>(value_in as f32)?;

        // Check if the conversion is exact by comparing the original f64 value with the f32 value converted back to f64
        if (value_out as f64) != value_in {
            let precision_out = value_out.precision_bits();

            return Err(RawRealConversionError::NonRepresentableExactly {
                value_in,
                value_out,
                precision_out,
                backtrace: capture_backtrace(),
            });
        }

        Ok(value_out)
    }
}

impl TryConvertFromRawReal<f32> for f64 {
    fn try_convert_from_raw_real(
        value_in: f32,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<f32, f64>> {
        try_validity_precision_out::<f32, f64>(&value_in, precision_out)?;

        let value_in = try_validate_input_value::<f32, f64>(value_in)?;

        // convert f32 to f64 (this is always exact)
        Ok(value_in as f64)
    }
}

#[duplicate_item(
    RawRealOut func_rug_to_native;
    [f64]      [to_f64()];
    [f32]      [to_f32()];
)]
#[cfg(feature = "rug")]
impl TryConvertFromRawReal<rug::Float> for RawRealOut {
    fn try_convert_from_raw_real(
        value_in: rug::Float,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<rug::Float, Self>> {
        try_validity_precision_out::<rug::Float, RawRealOut>(&value_in, precision_out)?;

        let value_in = try_validate_input_value::<rug::Float, RawRealOut>(value_in)?;

        // convert to RawRealOut and check if RawRealOut can represent the value exactly
        let value_out =
            try_validate_output_value::<rug::Float, RawRealOut>(value_in.func_rug_to_native)?;

        // Check if the conversion is exact by comparing the original rug::Float value with the RawRealOut value converted back to rug::Float
        let precision_in = value_in.precision_bits();
        let value_roundtrip = rug::Float::with_val(precision_in, value_out);
        if value_roundtrip != value_in {
            let precision_out = value_out.precision_bits();

            return Err(RawRealConversionError::NonRepresentableExactly {
                value_in,
                value_out,
                precision_out,
                backtrace: capture_backtrace(),
            });
        }

        Ok(value_out)
    }
}

#[cfg(feature = "rug")]
impl TryConvertFromRawReal<rug::Float> for rug::Float {
    fn try_convert_from_raw_real(
        value_in: rug::Float,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<rug::Float, Self>> {
        let value_in = try_validate_input_value::<rug::Float, rug::Float>(value_in)?;

        let precision_in = value_in.precision_bits();
        if precision_out == precision_in {
            Ok(value_in)
        } else {
            // Convert to rug::Float at requested precision and validate output.
            let value_out = try_validate_output_value::<rug::Float, rug::Float>(
                rug::Float::with_val(precision_out, &value_in),
            )?;

            // Ensure exact representability at requested precision.
            let value_roundtrip = rug::Float::with_val(precision_in, &value_out);
            if value_roundtrip != value_in {
                return Err(RawRealConversionError::NonRepresentableExactly {
                    value_in,
                    value_out,
                    precision_out,
                    backtrace: capture_backtrace(),
                });
            }

            Ok(value_out)
        }
    }
}

#[duplicate_item(
    RawRealIn  func_rug_to_native;
    [f64]      [to_f64()];
    [f32]      [to_f32()];
)]
#[cfg(feature = "rug")]
impl TryConvertFromRawReal<RawRealIn> for rug::Float {
    fn try_convert_from_raw_real(
        value_in: RawRealIn,
        precision_out: u32,
    ) -> Result<Self, RawRealConversionError<RawRealIn, Self>> {
        let value_in = try_validate_input_value::<RawRealIn, rug::Float>(value_in)?;

        // convert to rug::Float and check if can represent the input value exactly
        let value_out = try_validate_output_value::<RawRealIn, rug::Float>(rug::Float::with_val(
            precision_out,
            value_in,
        ))?;

        let value_roundtrip = value_out.func_rug_to_native;
        if value_roundtrip != value_in {
            return Err(RawRealConversionError::NonRepresentableExactly {
                value_in,
                value_out,
                precision_out,
                backtrace: capture_backtrace(),
            });
        }

        Ok(value_out)
    }
}

// =============================================================================
// Complex Trait
// =============================================================================

/// A trait for raw complex scalar types, extending [`RawScalarTrait`].
///
/// This trait is implemented by the underlying complex number types within a kernel,
/// such as [`num::Complex<f64>`]. It builds upon [`RawScalarTrait`] by adding operations
/// that are unique to complex numbers.
///
/// # Trait Bounds
///
/// - `RawScalarTrait<...>`: Ensures the type is a raw scalar and fixes its validation
///   error type to [`ErrorsValidationRawComplex`], which in turn wraps the validation
///   error of the associated real type. This establishes a consistent error structure.
/// - [`Conjugate`]: Requires that the complex number can be conjugated.
///
/// # Associated Types
///
/// - `type RawReal: RawRealTrait<RawComplex = Self>`: This is a critical part of the
///   design. It links the complex type to its underlying real component type (e.g., [`f64`]
///   for [`num::Complex<f64>`]). This associated real type must itself implement [`RawRealTrait`],
///   creating a two-way link between the real and complex raw types.
///
/// # Methods
///
/// This trait provides methods for accessing components and performing complex-specific
/// mathematical operations without validation checks.
pub trait RawComplexTrait:
    RawScalarTrait<
        ValidationError = ErrorsValidationRawComplex<ErrorsValidationRawReal<Self::RawReal>>,
    > + Conjugate
    + for<'a> Mul<&'a Self::RawReal, Output = Self>
    + for<'a> MulAssign<&'a Self::RawReal>
{
    /// The associated real type that makes up the components of this complex type.
    type RawReal: RawRealTrait<RawComplex = Self>;

    /// Creates a new complex number from real and imaginary parts without validation.
    fn new_unchecked_raw_complex(real: Self::RawReal, imag: Self::RawReal) -> Self;

    /// Computes the absolute value (modulus or norm) of `self` without validation.
    ///
    /// **Contract:** The caller must ensure the input is valid for this operation.
    fn unchecked_abs(self) -> Self::RawReal;

    /// Returns a reference to the real part of the complex number.
    fn raw_real_part(&self) -> &Self::RawReal;

    /// Returns a reference to the imaginary part of the complex number.
    fn raw_imag_part(&self) -> &Self::RawReal;

    /// Returns a mutable reference to the real part of the complex number.
    fn mut_raw_real_part(&mut self) -> &mut Self::RawReal;

    /// Returns a mutable reference to the imaginary part of the complex number.
    fn mut_raw_imag_part(&mut self) -> &mut Self::RawReal;

    /// Computes the argument (or phase) of `self` in radians, without validation.
    ///
    /// **Contract:** The caller must ensure that `self` is not zero.
    fn unchecked_arg(self) -> Self::RawReal;

    /// Raises `self` to the power of a real `exponent` without validation.
    ///
    /// **Contract:** The caller must ensure the inputs are valid for the power function.
    fn unchecked_pow_exponent_real(self, exponent: &Self::RawReal) -> Self;
}

#[cfg(test)]
mod tests_try_convert_from_raw_real {
    use super::*;
    use crate::core::errors::RawRealConversionError;

    mod native {
        use super::*;

        #[test]
        fn identity_f32_success() {
            let value = 1.5_f32;
            let converted: f32 = value.try_convert(24).unwrap();
            assert_eq!(converted, value);
        }

        #[test]
        fn identity_f32_invalid_output_precision() {
            let value = 1.5_f32;
            let result = value.try_convert::<f32>(53);
            assert!(matches!(
                result,
                Err(RawRealConversionError::InvalidOutputPrecision { .. })
            ));
        }

        #[test]
        fn identity_f64_success() {
            let value = 1.5_f64;
            let converted: f64 = value.try_convert(53).unwrap();
            assert_eq!(converted, value);
        }

        #[test]
        fn identity_f64_invalid_output_precision() {
            let value = 1.5_f64;
            let result = value.try_convert::<f64>(24);
            assert!(matches!(
                result,
                Err(RawRealConversionError::InvalidOutputPrecision { .. })
            ));
        }

        #[test]
        fn f64_to_f32_success() {
            let value = 1.5_f64;
            let converted: f32 = value.try_convert(24).unwrap();
            assert_eq!(converted, 1.5_f32);
        }

        #[test]
        fn f64_to_f32_non_representable_exactly() {
            let value = 0.1_f64;
            let result = value.try_convert::<f32>(24);
            assert!(matches!(
                result,
                Err(RawRealConversionError::NonRepresentableExactly { .. })
            ));
        }

        #[test]
        fn f64_to_f32_invalid_output_precision() {
            let value = 1.5_f64;
            let result = value.try_convert::<f32>(53);
            assert!(matches!(
                result,
                Err(RawRealConversionError::InvalidOutputPrecision { .. })
            ));
        }

        #[test]
        fn f32_to_f64_success() {
            let value = 1.5_f32;
            let converted: f64 = value.try_convert(53).unwrap();
            assert_eq!(converted, 1.5_f64);
        }

        #[test]
        fn f32_to_f64_invalid_output_precision() {
            let value = 1.5_f32;
            let result = value.try_convert::<f64>(24);
            assert!(matches!(
                result,
                Err(RawRealConversionError::InvalidOutputPrecision { .. })
            ));
        }
    }

    #[cfg(feature = "rug")]
    mod rug {
        use super::*;

        #[test]
        fn rug_to_f64_success() {
            let value = ::rug::Float::with_val(80, 1.5);
            let converted: f64 = value.try_convert(53).unwrap();
            assert_eq!(converted, 1.5_f64);
        }

        #[test]
        fn rug_to_f32_success() {
            let value = ::rug::Float::with_val(80, 1.5);
            let converted: f32 = value.try_convert(24).unwrap();
            assert_eq!(converted, 1.5_f32);
        }

        #[test]
        fn rug_to_f64_invalid_output_precision() {
            let value = ::rug::Float::with_val(80, 1.5);
            let result = value.try_convert::<f64>(24);
            assert!(matches!(
                result,
                Err(RawRealConversionError::InvalidOutputPrecision { .. })
            ));
        }

        #[test]
        fn rug_to_f32_non_representable_exactly() {
            let value = ::rug::Float::with_val(200, 0.1);
            let result = value.try_convert::<f32>(24);
            assert!(matches!(
                result,
                Err(RawRealConversionError::NonRepresentableExactly { .. })
            ));
        }

        #[test]
        fn f64_to_rug_success() {
            let value = 1.5_f64;
            let converted: ::rug::Float = value.try_convert(80).unwrap();
            assert_eq!(converted.to_f64(), 1.5_f64);
            assert_eq!(converted.precision_bits(), 80);
        }

        #[test]
        fn f32_to_rug_success() {
            let value = 1.5_f32;
            let converted: ::rug::Float = value.try_convert(80).unwrap();
            assert_eq!(converted.to_f32(), 1.5_f32);
            assert_eq!(converted.precision_bits(), 80);
        }

        #[test]
        fn f64_to_rug_non_representable_exactly_with_low_precision() {
            let value = std::f64::consts::PI;
            let result = value.try_convert::<::rug::Float>(10);
            assert!(matches!(
                result,
                Err(RawRealConversionError::NonRepresentableExactly { .. })
            ));
        }

        #[test]
        fn rug_to_rug_same_precision_success() {
            let value = ::rug::Float::with_val(80, 1.5);
            let converted: ::rug::Float = value.try_convert(80).unwrap();
            assert_eq!(converted.precision_bits(), 80);
            assert_eq!(converted.to_f64(), 1.5_f64);
        }

        #[test]
        fn rug_to_rug_higher_precision_success() {
            let value = ::rug::Float::with_val(53, 1.5);
            let converted: ::rug::Float = value.try_convert(200).unwrap();
            assert_eq!(converted.precision_bits(), 200);
            assert_eq!(converted.to_f64(), 1.5_f64);
        }

        #[test]
        fn rug_to_rug_non_representable_exactly_with_low_precision() {
            let value = ::rug::Float::with_val(200, std::f64::consts::PI);
            let result = value.try_convert::<::rug::Float>(10);
            assert!(matches!(
                result,
                Err(RawRealConversionError::NonRepresentableExactly { .. })
            ));
        }
    }
}