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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
//! # Numerical Kernels and Validated Types
//!
//! This module is the core of the numerical backend for the [`num-valid`](crate) crate.
//! It defines the fundamental traits, types, and operations for floating-point arithmetic.
//!
//! ## Core Architecture
//!
//! The architecture is built on three key concepts:
//!
//! 1. **Raw Traits ([`RawScalarTrait`], [`RawRealTrait`], [`RawComplexTrait`]):**
//! These traits define the baseline contract for a "raw" number type (like [`f64`] or
//! [`rug::Float`](https://docs.rs/rug/latest/rug/struct.Float.html)).
//! They provide a comprehensive set of `unchecked_*` methods for arithmetic and mathematical
//! functions. The "unchecked" prefix signifies that these methods do **not** perform
//! any validation (e.g., for domain, finiteness, or division by zero) and are intended
//! for internal use where validity has already been confirmed.
//!
//! 2. **Validated Structs ([`RealValidated`], [`ComplexValidated`]):**
//! These are wrapper types (newtypes) that enforce correctness. An instance of `RealValidated<P>`
//! is guaranteed to hold a raw value that has been successfully validated against the policy `P`.
//! All operations on these types (addition, `sqrt`, etc.) are designed to preserve this validity,
//! either by returning a `Result` or by panicking on failure in debug builds.
//!
//! 3. **Validation Policies ([`NumKernel`]):**
//! This trait allows the validation strategy to be generic. A kernel can be configured with
//! different policies, such as [`NumKernelStrictFinite`], which ensures all numbers are
//! finite (not NaN or Infinity).
//!
//! ## Available Kernels
//!
//! The library provides concrete kernels that bundle these concepts:
//!
//! - **`native64`:** Uses Rust's standard [`f64`] and `num::Complex<f64>` as the raw types.
//! This is the default, high-performance kernel.
//!
//! - **`rug` (feature-gated):** Uses arbitrary-precision types from the [`rug`](https://crates.io/crates/rug) crate,
//! ideal for high-precision scientific computing.
pub use crate;
// Re-export raw traits from core::traits::raw
pub use crate;
use crate;
use PhantomData;
//------------------------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
/// A strict finite kernel validation policy for raw real numbers.
/// This policy ensures that the real numbers are finite and not NaN.
//-----------------------------------------------------------------------------------------------
//-----------------------------------------------------------------------------------------------
/// A debug-only strict finite kernel validation policy for raw real numbers.
///
/// This kernel applies [`StrictFinitePolicy`] validation only in debug builds.
/// In release builds, validation is skipped for maximum performance.
///
/// ## Use Cases
///
/// - Performance-critical code where validation overhead is unacceptable in production
/// - Code that has been thoroughly tested with [`NumKernelStrictFinite`] in debug mode
///
/// ## Comparison with `NumKernelStrictFinite`
///
/// | Aspect | `NumKernelStrictFinite` | `NumKernelStrictFiniteInDebug` |
/// |--------|-------------------------|--------------------------------|
/// | Debug validation | ✅ Yes | ✅ Yes |
/// | Release validation | ✅ Yes | ❌ No |
/// | `Eq + Hash + Ord` | ✅ Yes | ❌ No (not safe without validation) |
/// | Performance | Slower | Faster in release |
///
/// ## Safety Note
///
/// Since validation is skipped in release builds, this kernel does NOT implement
/// the [`GuaranteesFiniteRealValues`](crate::core::traits::validation::GuaranteesFiniteRealValues)
/// marker trait, meaning it cannot be used with `HashMap`, `BTreeMap`, or other
/// collections requiring `Eq` + `Hash` + `Ord`.
//-----------------------------------------------------------------------------------------------