num_valid/core/

policies.rs

#![deny(rustdoc::broken_intra_doc_links)]

//! Validation policies for scalar types.
//!
//! This module provides the validation policies that determine how scalar values
//! are checked for validity. The primary policy is `StrictFinitePolicy`, which
//! ensures values are finite and not subnormal.

use crate::core::{
    errors::{ErrorsValidationRawComplex, ErrorsValidationRawReal},
    traits::{
        raw::{RawComplexTrait, RawRealTrait, RawScalarValidate},
        validation::{
            GuaranteesFiniteComplexValues, GuaranteesFiniteRealValues, ValidationPolicyComplex,
            ValidationPolicyReal,
        },
    },
};
use duplicate::duplicate_item;
use num::Complex;
use std::marker::PhantomData;
use try_create::ValidationPolicy;

/// A validation policy that checks for strict finiteness.
///
/// For floating-point types (`ScalarType = `[`f32`], `ScalarType = `[`f64`], `ScalarType = `[`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html)), this policy ensures that the value is:
/// - Not NaN (Not a Number).
/// - Not positive or negative Infinity.
/// - Not subnormal (for `f32`/`f64`).
///   While [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) maintains its specified precision rather than having distinct subnormal
///   representation in the IEEE 754 sense, this policy will also reject [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) values that are classified as
///   [`FpCategory::Subnormal`](std::num::FpCategory::Subnormal) (e.g., results of underflow that are tiny but not exactly zero).
///
/// For complex types (`ScalarType = `[`Complex<f32>`], `ScalarType = `[`Complex<f64>`], `ScalarType = `[`rug::Complex`](https://docs.rs/rug/latest/rug/struct.Complex.html)), this policy applies
/// the strict finiteness check to both the real and imaginary parts.
///
/// This struct is a Zero-Sized Type (ZST) and uses [`PhantomData`] to associate
/// with the `ScalarType` it validates.
pub struct StrictFinitePolicy<ScalarType: Sized, const PRECISION: u32>(PhantomData<ScalarType>);

/// A type alias for a validation policy that enforces strict finiteness for the raw [`f64`] type.
///
/// This is a convenient alias for [`StrictFinitePolicy<f64, 53>`], configured specifically
/// for Rust's native 64-bit floating-point number. It is used to validate that a given [`f64`]
/// value is suitable for use within the library's validated types.
///
/// This policy ensures that a `f64` value is:
/// - Not `NaN` (Not a Number).
/// - Not positive or negative `Infinity`.
/// - Not a subnormal number.
///
/// It is a fundamental building block for the native `f64` kernel, providing the validation
/// logic for [`RealNative64StrictFinite`](crate::backends::native::validated::RealNative64StrictFinite).
///
/// # Example
///
/// ```rust
/// use num_valid::{
///     core::{
///         errors::ErrorsValidationRawReal,
///         policies::Native64RawRealStrictFinitePolicy,
///     },
/// };
/// use try_create::ValidationPolicy;
///
/// // A valid finite number passes validation.
/// assert!(Native64RawRealStrictFinitePolicy::validate(1.0).is_ok());
///
/// // NaN fails validation.
/// let result_nan = Native64RawRealStrictFinitePolicy::validate(f64::NAN);
/// assert!(matches!(result_nan, Err(ErrorsValidationRawReal::IsNaN { .. })));
///
/// // Infinity fails validation.
/// let result_inf = Native64RawRealStrictFinitePolicy::validate(f64::INFINITY);
/// assert!(matches!(result_inf, Err(ErrorsValidationRawReal::IsPosInfinity { .. })));
/// ```
pub type Native64RawRealStrictFinitePolicy = StrictFinitePolicy<f64, { f64::MANTISSA_DIGITS }>;

/// A type alias for a validation policy that enforces strict finiteness for the raw [`num::Complex<f64>`] type.
///
/// This is a convenient alias for [`StrictFinitePolicy<Complex<f64>, 53>`], configured for
/// Rust's native 64-bit complex numbers. It is used to validate that a given [`num::Complex<f64>`]
/// value is suitable for use within the library's validated types.
///
/// This policy applies the strict finiteness check (as defined by [`Native64RawRealStrictFinitePolicy`])
/// to both the real and imaginary parts of the complex number. A [`num::Complex<f64>`] value is considered
/// valid if and only if both of its components are finite (not `NaN`, `Infinity`, or subnormal).
///
/// It is a fundamental building block for the native `f64` kernel, providing the validation
/// logic for [`ComplexNative64StrictFinite`](crate::backends::native::validated::ComplexNative64StrictFinite).
///
/// # Example
///
/// ```rust
/// use num_valid::{
///     core::{
///         errors::{ErrorsValidationRawComplex, ErrorsValidationRawReal},
///         policies::Native64RawComplexStrictFinitePolicy,
///     },
/// };
/// use try_create::ValidationPolicy;
/// use num::Complex;
///
/// // A complex number with valid finite parts passes validation.
/// let valid_complex = Complex::new(1.0, -2.0);
/// assert!(Native64RawComplexStrictFinitePolicy::validate(valid_complex).is_ok());
///
/// // A complex number with NaN in the real part fails validation.
/// let nan_complex = Complex::new(f64::NAN, 2.0);
/// let result_nan = Native64RawComplexStrictFinitePolicy::validate(nan_complex);
/// assert!(matches!(result_nan, Err(ErrorsValidationRawComplex::InvalidRealPart { .. })));
///
/// // A complex number with Infinity in the imaginary part fails validation.
/// let inf_complex = Complex::new(1.0, f64::INFINITY);
/// let result_inf = Native64RawComplexStrictFinitePolicy::validate(inf_complex);
/// assert!(matches!(result_inf, Err(ErrorsValidationRawComplex::InvalidImaginaryPart { .. })));
///
/// // A complex number with invalid parts in both also fails.
/// let both_invalid = Complex::new(f64::NAN, f64::INFINITY);
/// let result_both = Native64RawComplexStrictFinitePolicy::validate(both_invalid);
/// assert!(matches!(result_both, Err(ErrorsValidationRawComplex::InvalidBothParts { .. })));
/// ```
pub type Native64RawComplexStrictFinitePolicy =
    StrictFinitePolicy<Complex<f64>, { f64::MANTISSA_DIGITS }>;

/// A type alias for a validation policy that enforces strict finiteness for the raw [`f32`] type.
///
/// This is a convenient alias for [`StrictFinitePolicy<f32, 24>`], configured specifically
/// for Rust's native 32-bit floating-point number. It is used to validate that a given [`f32`]
/// value is suitable for use within the library's validated types.
///
/// This policy ensures that a `f32` value is:
/// - Not `NaN` (Not a Number).
/// - Not positive or negative `Infinity`.
/// - Not a subnormal number.
///
/// It is a fundamental building block for the native `f32` kernel, providing the validation
/// logic for [`RealNative32StrictFinite`](crate::backends::native::validated::RealNative32StrictFinite).
///
/// # Example
///
/// ```rust
/// use num_valid::{
///     core::{
///         errors::ErrorsValidationRawReal,
///         policies::Native32RawRealStrictFinitePolicy,
///     },
/// };
/// use try_create::ValidationPolicy;
///
/// // A valid finite number passes validation.
/// assert!(Native32RawRealStrictFinitePolicy::validate(1.0).is_ok());
///
/// // NaN fails validation.
/// let result_nan = Native32RawRealStrictFinitePolicy::validate(f32::NAN);
/// assert!(matches!(result_nan, Err(ErrorsValidationRawReal::IsNaN { .. })));
///
/// // Infinity fails validation.
/// let result_inf = Native32RawRealStrictFinitePolicy::validate(f32::INFINITY);
/// assert!(matches!(result_inf, Err(ErrorsValidationRawReal::IsPosInfinity { .. })));
/// ```
pub type Native32RawRealStrictFinitePolicy = StrictFinitePolicy<f32, { f32::MANTISSA_DIGITS }>;

/// A type alias for a validation policy that enforces strict finiteness for the raw [`num::Complex<f32>`] type.
///
/// This is a convenient alias for [`StrictFinitePolicy<Complex<f32>, 24>`], configured for
/// Rust's native 32-bit complex numbers. It is used to validate that a given [`num::Complex<f32>`]
/// value is suitable for use within the library's validated types.
///
/// This policy applies the strict finiteness check (as defined by [`Native32RawRealStrictFinitePolicy`])
/// to both the real and imaginary parts of the complex number. A [`num::Complex<f32>`] value is considered
/// valid if and only if both of its components are finite (not `NaN`, `Infinity`, or subnormal).
///
/// It is a fundamental building block for the native `f32` kernel, providing the validation
/// logic for [`ComplexNative32StrictFinite`](crate::backends::native::validated::ComplexNative32StrictFinite).
///
/// # Example
///
/// ```rust
/// use num_valid::{
///     core::{
///         errors::{ErrorsValidationRawComplex, ErrorsValidationRawReal},
///         policies::Native32RawComplexStrictFinitePolicy,
///     },
/// };
/// use try_create::ValidationPolicy;
/// use num::Complex;
///
/// // A complex number with valid finite parts passes validation.
/// let valid_complex = Complex::new(1.0, -2.0);
/// assert!(Native32RawComplexStrictFinitePolicy::validate(valid_complex).is_ok());
///
/// // A complex number with NaN in the real part fails validation.
/// let nan_complex = Complex::new(f32::NAN, 2.0);
/// let result_nan = Native32RawComplexStrictFinitePolicy::validate(nan_complex);
/// assert!(matches!(result_nan, Err(ErrorsValidationRawComplex::InvalidRealPart { .. })));
///
/// // A complex number with Infinity in the imaginary part fails validation.
/// let inf_complex = Complex::new(1.0, f32::INFINITY);
/// let result_inf = Native32RawComplexStrictFinitePolicy::validate(inf_complex);
/// assert!(matches!(result_inf, Err(ErrorsValidationRawComplex::InvalidImaginaryPart { .. })));
///
/// // A complex number with invalid parts in both also fails.
/// let both_invalid = Complex::new(f32::NAN, f32::INFINITY);
/// let result_both = Native32RawComplexStrictFinitePolicy::validate(both_invalid);
/// assert!(matches!(result_both, Err(ErrorsValidationRawComplex::InvalidBothParts { .. })));
/// ```
pub type Native32RawComplexStrictFinitePolicy =
    StrictFinitePolicy<Complex<f32>, { f32::MANTISSA_DIGITS }>;

/// Ensures the `f32`/`f64` value is strictly finite.
///
/// This policy checks if the `f32`/`f64` value is:
/// - Not NaN (Not a Number).
/// - Not positive or negative Infinity.
/// - Not subnormal.
///
/// # Errors
///
/// Returns [`ErrorsValidationRawReal`] if the value
/// fails any of these checks.
#[duplicate_item(
    T mantissa_digits;
    [f32] [24];
    [f64] [53];
)]
impl ValidationPolicy for StrictFinitePolicy<T, mantissa_digits> {
    type Value = T;
    type Error = ErrorsValidationRawReal<T>;

    #[inline(always)]
    fn validate_ref(value: &T) -> Result<(), Self::Error> {
        value.validate_raw_scalar_ref()
    }
}

//------------------------------------------------------------------------------------------------
/// A validation policy that is active only in debug builds.
///
/// This struct acts as a wrapper around another [`ValidationPolicy`].
///
/// - In **debug builds** (`#[cfg(debug_assertions)]`), it delegates validation
///   directly to the inner policy `P`.
/// - In **release builds** (`#[cfg(not(debug_assertions))]`), it becomes a "no-op"
///   (no operation), meaning its `validate` and `validate_ref` methods do nothing
///   and always return `Ok`.
///
/// This is useful for enforcing strict, potentially expensive validations during
/// development and testing, while eliminating their performance overhead in production code.
///
/// # Generic Parameters
///
/// - `P`: The inner [`ValidationPolicy`] to use during debug builds.
///
/// # Example
///
/// ```rust,ignore
/// use num_valid::{validation::{DebugValidationPolicy, StrictFinitePolicy, Native64RawRealStrictFinitePolicy}};
/// use try_create::ValidationPolicy;
///
/// // Define a policy that uses Native64RawRealStrictFinitePolicy
/// // (i.e. StrictFinitePolicy<f64, 53>) only in debug builds.
/// type MyPolicy = DebugValidationPolicy<Native64RawRealStrictFinitePolicy>;
///
/// let nan_value = f64::NAN;
/// let result = MyPolicy::validate(nan_value);
///
/// #[cfg(debug_assertions)]
/// {
///     // In debug mode, the validation fails because StrictFinitePolicy catches NaN.
///     assert!(result.is_err());
/// }
///
/// #[cfg(not(debug_assertions))]
/// {
///     // In release mode, the validation is skipped and always succeeds.
///     assert!(result.is_ok());
/// }
/// ```
pub struct DebugValidationPolicy<P: ValidationPolicy>(PhantomData<P>);

impl<P: ValidationPolicy> ValidationPolicy for DebugValidationPolicy<P> {
    type Value = P::Value;
    type Error = P::Error;

    #[inline(always)]
    fn validate_ref(value: &Self::Value) -> Result<(), Self::Error> {
        // In debug builds, this implementation delegates to the inner policy `P`.
        #[cfg(debug_assertions)]
        {
            // Delegate to the inner policy's validation logic.
            P::validate_ref(value)
        }
        #[cfg(not(debug_assertions))]
        {
            let _ = value; // Avoid unused variable warning in release mode.
            // In release mode, this is a no-op.
            // The validation is skipped, and we always return Ok.
            // This allows the compiler to optimize away the validation logic entirely.
            // This is useful for performance-critical code where validation is not needed in production.
            // Note: The `value` is not used here, but we keep it to match the signature of `validate_ref`.
            // This way, we can still call this method without needing to change the function signature.
            // This is particularly useful when this policy is used in generic contexts
            // where the `validate_ref` method is expected to take a reference to the value.
            // The `PhantomData` ensures that the type system knows about `P` even
            // though we don't use it directly in the release build.
            // This is a common pattern in Rust to create zero-sized types that carry type information.
            Ok(())
        }
    }
}

impl<P> ValidationPolicyReal for DebugValidationPolicy<P>
where
    P: ValidationPolicyReal,
{
    const PRECISION: u32 = P::PRECISION;
}

impl<P> ValidationPolicyComplex for DebugValidationPolicy<P>
where
    P: ValidationPolicyComplex,
{
    const PRECISION: u32 = P::PRECISION;
}
//------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------
/// Validates a complex number by checking both its real and imaginary parts.
///
/// This function uses the provided real validation function `validation_func_raw_real` to
/// validate both parts.
/// If both parts are valid, it returns `Ok(())`. If either part is invalid,
/// it returns an appropriate error variant from the `ErrorsValidationRawComplex` enum.
///
/// # Errors
/// Returns [`ErrorsValidationRawComplex<P::Error>`](ErrorsValidationRawComplex)
/// if either the real part, the imaginary part, or both parts fail validation
/// using the real validation function `validation_func_raw_real`.
pub(crate) fn validate_complex_from_parts<T: RawRealTrait>(
    real_part: &T,
    imag_part: &T,
    validation_func_raw_real: fn(&T) -> Result<(), ErrorsValidationRawReal<T>>,
) -> Result<(), ErrorsValidationRawComplex<ErrorsValidationRawReal<T>>> {
    let real_validation = validation_func_raw_real(real_part);
    let imag_validation = validation_func_raw_real(imag_part);
    match (real_validation, imag_validation) {
        (Ok(()), Ok(())) => Ok(()),
        (Ok(()), Err(imag_err)) => Err(ErrorsValidationRawComplex::InvalidImaginaryPart {
            source: Box::new(imag_err),
        }),
        (Err(real_err), Ok(())) => Err(ErrorsValidationRawComplex::InvalidRealPart {
            source: Box::new(real_err),
        }),
        (Err(real_err), Err(imag_err)) => Err(ErrorsValidationRawComplex::InvalidBothParts {
            real_error: Box::new(real_err),
            imag_error: Box::new(imag_err),
        }),
    }
}
//------------------------------------------------------------------------------------------------

//-------------------------------------------------------------
/// Validates a value using the given policy, but only in debug builds.
/// In release builds, this function is a no-op and should be optimized away.
///
/// # Panics
///
/// In debug builds, this function will panic if `P::validate_ref(value)` returns an `Err`.
#[inline(always)]
pub fn validate_in_debug<P: ValidationPolicy>(value: &P::Value, msg: &str) {
    #[cfg(debug_assertions)]
    {
        if let Err(e) = P::validate_ref(value) {
            panic!("Debug validation of {msg} value failed: {e}");
        }
    }
    #[cfg(not(debug_assertions))]
    {
        // These are no-op in release builds
        let _ = value;
        let _ = msg;
    }
}
//--------------------------------------------------------------------------------------------------

//--------------------------------------------------------------------------------------------------
/// Ensures both the real and imaginary parts of a `Complex<f64>` value are strictly finite.
///
/// This policy applies the [`StrictFinitePolicy<f64>`](StrictFinitePolicy) to both
/// the real and imaginary components of the complex number.
///
/// # Errors
///
/// Returns [`ErrorsValidationRawComplex<ErrorsValidationRawReal<f64>>`](ErrorsValidationRawComplex)
/// if either the real part, the imaginary part, or both parts fail the
/// `StrictFinitePolicy<f64>` checks.
#[duplicate_item(
    T mantissa_digits;
    [f32] [24];
    [f64] [53];
)]
impl ValidationPolicy for StrictFinitePolicy<Complex<T>, mantissa_digits> {
    type Value = Complex<T>;
    type Error = ErrorsValidationRawComplex<ErrorsValidationRawReal<T>>;

    fn validate_ref(value: &Complex<T>) -> Result<(), Self::Error> {
        validate_complex_from_parts(
            &value.re,
            &value.im,
            StrictFinitePolicy::<T, mantissa_digits>::validate_ref,
        )
    }
}

impl<RawReal: RawRealTrait, const PRECISION: u32> ValidationPolicyReal
    for StrictFinitePolicy<RawReal, PRECISION>
where
    StrictFinitePolicy<RawReal, PRECISION>:
        ValidationPolicy<Value = RawReal, Error = <RawReal as RawScalarValidate>::ValidationError>,
{
    const PRECISION: u32 = PRECISION;
}

impl<RawComplex: RawComplexTrait, const PRECISION: u32> ValidationPolicyComplex
    for StrictFinitePolicy<RawComplex, PRECISION>
where
    StrictFinitePolicy<RawComplex, PRECISION>: ValidationPolicy<
            Value = RawComplex,
            Error = <RawComplex as RawScalarValidate>::ValidationError,
        >,
{
    const PRECISION: u32 = PRECISION;
}

//--------------------------------------------------------------------------------------------------
// Rug Implementations (conditional compilation)
//--------------------------------------------------------------------------------------------------

#[cfg(feature = "rug")]
pub(crate) mod rug_impls {
    use super::*; // Imports items from the parent module (validation)
    use crate::core::errors::capture_backtrace;
    use std::num::FpCategory;

    /// Ensures the [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) value is strictly finite.
    ///
    /// This policy checks if the underlying [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) value:
    /// - Is not NaN (Not a Number).
    /// - Is not positive nor negative Infinity.
    /// - Has the specified precision (equal to `PRECISION`).
    ///
    /// Note: [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) does not have a direct concept of "subnormal" in the same
    /// way IEEE 754 floats do; it maintains its specified precision.
    ///
    /// # Errors
    ///
    /// Returns [`ErrorsValidationRawReal<rug::Float>`](ErrorsValidationRawReal)
    /// if the value fails any of these checks.
    impl<const PRECISION: u32> ValidationPolicy for StrictFinitePolicy<rug::Float, PRECISION> {
        type Value = rug::Float;
        type Error = ErrorsValidationRawReal<rug::Float>;

        fn validate_ref(value: &rug::Float) -> Result<(), Self::Error> {
            let actual_precision = value.prec();
            if actual_precision == PRECISION {
                // rug::Float uses std::num::FpCategory via its own classify method
                match value.classify() {
                    FpCategory::Infinite => {
                        if value.is_sign_positive() {
                            Err(ErrorsValidationRawReal::IsPosInfinity {
                                backtrace: capture_backtrace(),
                            })
                        } else {
                            Err(ErrorsValidationRawReal::IsNegInfinity {
                                backtrace: capture_backtrace(),
                            })
                        }
                    }
                    FpCategory::Nan => Err(ErrorsValidationRawReal::IsNaN {
                        value: value.clone(),
                        backtrace: capture_backtrace(),
                    }),
                    FpCategory::Subnormal => Err(ErrorsValidationRawReal::IsSubnormal {
                        value: value.clone(),
                        backtrace: capture_backtrace(),
                    }),
                    FpCategory::Zero | FpCategory::Normal => Ok(()),
                }
            } else {
                Err(ErrorsValidationRawReal::PrecisionMismatch {
                    input_value: value.clone(),
                    actual_precision,
                    requested_precision: PRECISION,
                    backtrace: capture_backtrace(),
                })
            }
        }
    }

    /// Ensures both the real and imaginary parts of a [`rug::Complex`](https://docs.rs/rug/latest/rug/struct.Complex.html) value are strictly finite.
    ///
    /// This policy applies the [`StrictFinitePolicy<rug::Float>`]
    /// (which checks the underlying [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html)) to both the real and imaginary
    /// components of the [`rug::Complex`](https://docs.rs/rug/latest/rug/struct.Complex.html).
    ///
    /// # Errors
    ///
    /// Returns [`ErrorsValidationRawComplex<ErrorsValidationRawReal<rug::Float>>`](ErrorsValidationRawComplex)
    /// if either the real part, the imaginary part, or both parts fail the
    /// `StrictFinitePolicy<RealRugStrictFinite<Precision>>` checks.
    impl<const PRECISION: u32> ValidationPolicy for StrictFinitePolicy<rug::Complex, PRECISION> {
        type Value = rug::Complex;
        type Error = ErrorsValidationRawComplex<ErrorsValidationRawReal<rug::Float>>;

        fn validate_ref(value: &rug::Complex) -> Result<(), Self::Error> {
            validate_complex_from_parts(
                value.real(),
                value.imag(),
                StrictFinitePolicy::<rug::Float, PRECISION>::validate_ref,
            )
        }
    }
}
//-------------------------------------------------------------

// Implement the marker for `StrictFinitePolicy` for any real scalar type.
impl<RawReal: RawRealTrait, const PRECISION: u32> GuaranteesFiniteRealValues
    for StrictFinitePolicy<RawReal, PRECISION>
where
    // This bound is necessary to satisfy the supertrait requirements of GuaranteesFiniteRealValues
    StrictFinitePolicy<RawReal, PRECISION>: ValidationPolicyReal,
{
}

// Implement the marker for `DebugValidationPolicy<StrictFinitePolicy>` for any real scalar type.
impl<RawReal: RawRealTrait, const PRECISION: u32> GuaranteesFiniteRealValues
    for DebugValidationPolicy<StrictFinitePolicy<RawReal, PRECISION>>
where
    // This bound is necessary to satisfy the supertrait requirements of GuaranteesFiniteRealValues
    StrictFinitePolicy<RawReal, PRECISION>: ValidationPolicyReal,
{
}

// Implement the marker for `StrictFinitePolicy` for any complex scalar type.
impl<RawComplex: RawComplexTrait, const PRECISION: u32> GuaranteesFiniteComplexValues
    for StrictFinitePolicy<RawComplex, PRECISION>
where
    // This bound is necessary to satisfy the supertrait requirements of GuaranteesFiniteComplexValues
    StrictFinitePolicy<RawComplex, PRECISION>: ValidationPolicyComplex,
{
}

// Implement the marker for `DebugValidationPolicy<StrictFinitePolicy>` for any complex scalar type.
impl<RawComplex: RawComplexTrait, const PRECISION: u32> GuaranteesFiniteComplexValues
    for DebugValidationPolicy<StrictFinitePolicy<RawComplex, PRECISION>>
where
    // This bound is necessary to satisfy the supertrait requirements of GuaranteesFiniteComplexValues
    StrictFinitePolicy<RawComplex, PRECISION>: ValidationPolicyComplex,
{
}
//-------------------------------------------------------------