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

num_valid/core/
traits.rs
