num_valid/core/
traits.rs

1#![deny(rustdoc::broken_intra_doc_links)]
2
3//! Core trait definitions for the num-valid library.
4//!
5//! This module contains the fundamental traits that define the behavior
6//! of raw and validated scalar types.
7
8use crate::{
9    ComplexScalar, RealScalar,
10    core::traits::{
11        raw::RawScalarValidate,
12        validation::{ValidationPolicyComplex, ValidationPolicyReal},
13    },
14    kernels::{RawComplexTrait, RawRealTrait},
15};
16
17/// Raw trait contracts for unchecked operations on primitive types.
18pub mod raw;
19
20/// Validation traits and marker traits for finite value guarantees.
21pub mod validation;
22
23//------------------------------------------------------------------------------------------------------------
24/// Defines the identity of a raw numerical kernel by associating its fundamental types.
25///
26/// This trait acts as a low-level building block that groups the core "raw"
27/// types of a numerical backend. It specifies which concrete types implement
28/// [`RawRealTrait`] and [`RawComplexTrait`] for a given kernel.
29///
30/// It is primarily used as a supertrait for [`NumKernel`], which extends
31/// this type-level association with concrete validation logic and precision information.
32pub trait RawKernel: Send + Sync + 'static {
33    /// The raw real type associated with this kernel (e.g., [`f64`]).
34    type RawReal: RawRealTrait; // + TryConvertFromRawReal<f64>;
35
36    /// The raw complex type associated with this kernel (e.g., [`num::Complex<f64>`]).
37    type RawComplex: RawComplexTrait<RawReal = Self::RawReal>;
38}
39//------------------------------------------------------------------------------------------------------------
40
41//------------------------------------------------------------------------------------------------------------
42/// Defines a complete numerical kernel, acting as the central configuration point.
43///
44/// This trait is the primary bound for generic functions that need to operate
45/// across different numerical backends. It bundles together:
46/// 1.  The raw underlying types (e.g., `f64`) via the [`RawKernel`] supertrait.
47/// 2.  The specific validation logic for those types.
48/// 3.  The precision of the kernel in bits.
49/// 4.  The final, high-level `Real` and `Complex` validated types.
50pub trait NumKernel: RawKernel + Sized {
51    /// The validation policy for real numbers.
52    ///
53    /// # Note
54    /// The bound on `ValidationPolicyReal::Error` is a critical architectural choice. It enforces that the
55    /// error type defined by a policy (`RealPolicy::Error`) MUST be the same as the
56    /// canonical validation error type associated with its value (`RealPolicy::Value::ValidationError`).
57    /// This prevents mismatches and simplifies error handling throughout the library.
58    type RealPolicy: ValidationPolicyReal<
59            Value = Self::RawReal,
60            Error = <Self::RawReal as RawScalarValidate>::ValidationError,
61        >;
62
63    /// The validation policy for complex numbers.
64    ///
65    /// # Note
66    /// The bound on `ValidationPolicyComplex::Error` is a critical architectural choice. It enforces that the
67    /// error type defined by a policy (`ComplexPolicy::Error`) MUST be the same as the
68    /// canonical validation error type associated with its value (`ComplexPolicy::Value::ValidationError`).
69    /// This prevents mismatches and simplifies error handling throughout the library.
70    type ComplexPolicy: ValidationPolicyComplex<
71            Value = Self::RawComplex,
72            Error = <Self::RawComplex as RawScalarValidate>::ValidationError,
73        >;
74
75    /// The final, high-level, validated real scalar type for this kernel.
76    /// This is typically an alias for `RealValidated<Self>`.
77    type Real: RealScalar<RawReal = Self::RawReal>;
78
79    /// The final, high-level, validated complex scalar type for this kernel.
80    /// This is typically an alias for `ComplexValidated<Self>`.
81    /// The `RealType = Self::Real` bound ensures the complex type is composed of the
82    /// corresponding validated real type from the same kernel.
83    type Complex: ComplexScalar<RealType = Self::Real>;
84}
85//------------------------------------------------------------------------------------------------------------
num_valid/core/traits.rs

num_valid/core/
traits.rs
