num-valid 0.3.3

A robust numerical library providing validated types for real and complex numbers to prevent common floating-point errors like NaN propagation. Features a generic, layered architecture with support for native f64 and optional arbitrary-precision arithmetic.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

#![deny(rustdoc::broken_intra_doc_links)]

//! Core trait definitions for the num-valid library.
//!
//! This module contains the fundamental traits that define the behavior
//! of raw and validated scalar types.

use crate::{
    ComplexScalar, RealScalar,
    core::traits::validation::{ValidationPolicyComplex, ValidationPolicyReal},
    kernels::{RawComplexTrait, RawRealTrait, RawScalarTrait},
};

/// Raw trait contracts for unchecked operations on primitive types.
pub mod raw;

/// Validation traits and marker traits for finite value guarantees.
pub mod validation;

//------------------------------------------------------------------------------------------------------------
/// Defines the identity of a raw numerical kernel by associating its fundamental types.
///
/// This trait acts as a low-level building block that groups the core "raw"
/// types of a numerical backend. It specifies which concrete types implement
/// [`RawRealTrait`] and [`RawComplexTrait`] for a given kernel.
///
/// It is primarily used as a supertrait for [`NumKernel`], which extends
/// this type-level association with concrete validation logic and precision information.
pub trait RawKernel: Send + Sync + 'static {
    /// The raw real type associated with this kernel (e.g., [`f64`]).
    type RawReal: RawRealTrait;

    /// The raw complex type associated with this kernel (e.g., [`num::Complex<f64>`]).
    type RawComplex: RawComplexTrait<RawReal = Self::RawReal>;
}
//------------------------------------------------------------------------------------------------------------

//------------------------------------------------------------------------------------------------------------
/// Defines a complete numerical kernel, acting as the central configuration point.
///
/// This trait is the primary bound for generic functions that need to operate
/// across different numerical backends. It bundles together:
/// 1.  The raw underlying types (e.g., `f64`) via the [`RawKernel`] supertrait.
/// 2.  The specific validation logic for those types.
/// 3.  The precision of the kernel in bits.
/// 4.  The final, high-level `Real` and `Complex` validated types.
pub trait NumKernel: RawKernel + Sized {
    /// The validation policy for real numbers.
    ///
    /// # Note
    /// The bound on `ValidationPolicyReal::Error` is a critical architectural choice. It enforces that the
    /// error type defined by a policy (`RealPolicy::Error`) MUST be the same as the
    /// canonical validation error type associated with its value (`RealPolicy::Value::ValidationErrors`).
    /// This prevents mismatches and simplifies error handling throughout the library.
    type RealPolicy: ValidationPolicyReal<
            Value = Self::RawReal,
            Error = <Self::RawReal as RawScalarTrait>::ValidationErrors,
        >;

    /// The validation policy for complex numbers.
    ///
    /// # Note
    /// The bound on `ValidationPolicyComplex::Error` is a critical architectural choice. It enforces that the
    /// error type defined by a policy (`ComplexPolicy::Error`) MUST be the same as the
    /// canonical validation error type associated with its value (`ComplexPolicy::Value::ValidationErrors`).
    /// This prevents mismatches and simplifies error handling throughout the library.
    type ComplexPolicy: ValidationPolicyComplex<
            Value = Self::RawComplex,
            Error = <Self::RawComplex as RawScalarTrait>::ValidationErrors,
        >;

    /// The final, high-level, validated real scalar type for this kernel.
    /// This is typically an alias for `RealValidated<Self>`.
    type Real: RealScalar<RawReal = Self::RawReal>;

    /// The final, high-level, validated complex scalar type for this kernel.
    /// This is typically an alias for `ComplexValidated<Self>`.
    /// The `RealType = Self::Real` bound ensures the complex type is composed of the
    /// corresponding validated real type from the same kernel.
    type Complex: ComplexScalar<RealType = Self::Real>;
}
//------------------------------------------------------------------------------------------------------------