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, ErrorsTryFromf64, ErrorsValidationRawComplex,
            ErrorsValidationRawReal,
        },
        traits::validation::{FpChecks, ValidationPolicyReal},
    },
    functions::{Rounding, Sign},
};
use std::{
    cmp::Ordering,
    hash::Hasher,
    num::FpCategory,
    ops::{Mul, MulAssign},
};

// =============================================================================
// 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;
}

// =============================================================================
// 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()`](Self::compute_hash),
/// 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
    + Arithmetic
    + NeumaierAddable
    + FpChecks
    + RawScalarTrigonometric
    + RawScalarHyperbolic
    + RawScalarPow
{
    /// The associated error type for validation failures of this raw type.
    type ValidationErrors: std::error::Error;

    /// 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()` 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<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<ValidationErrors = 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.
/// - [`PartialOrd<f64>`]: These crucial bounds allow instances of the raw
///   real type to be directly compared with `f64` constants. This is essential for implementing
///   domain checks (e.g., `value < 0.0` or `value >= 0.0`) that work across
///   both [`f64`] and [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html) without extra conversions.
///
/// # 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<ValidationErrors = ErrorsValidationRawReal<Self>>
    + PartialOrd
    + PartialOrd<f64>
    + Sign
    + Rounding
{
    /// 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;

    /// Tries to create a new raw real value from an `f64`.
    fn try_new_raw_real_from_f64<RealPolicy: ValidationPolicyReal<Value = Self>>(
        value: f64,
    ) -> Result<Self, ErrorsTryFromf64<Self>>;

    /// Returns the precision (in bits) of the raw real type.
    fn precision(&self) -> u32;

    /// 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>>;
}

// =============================================================================
// 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<
        ValidationErrors = 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;
}