Expand description
§Numerical Value Validation Module
This module provides a framework for validating numerical scalar values,
particularly floating-point and complex numbers, including those with arbitrary precision
using the rug
library (when the “rug” feature is enabled).
It defines:
- Error Types: Such as
ErrorsValidationRawReal
,ErrorsValidationRawComplex
, andErrorsTryFromf64
. These errors detail various validation failures like non-finite values, subnormal numbers (forf64
andrug::Float
), and precision mismatches forrug
types. - Validation Policies: Implemented via the
ValidationPolicy
trait from thetry_create
crate. The primary policy provided isStrictFinitePolicy
, which ensures that numbers are finite (not NaN or Infinity) and, forf64
andrug::Float
, not subnormal. - Floating-Point Checks Trait: The
FpChecks
trait, defined within this module, provides common classification methods likeis_finite
,is_nan
,is_infinite
, andis_normal
. This trait is implemented for standard andrug
-based scalar types. - Enhanced Type Safety for HashMap Keys: The
GuaranteesFiniteValues
marker trait enables full equality (Eq
) and hashing (Hash
) for validated types when their validation policy guarantees finite values. This allows validated types to be used as keys inHashMap
and other hash-based collections. - Implementations: Validation logic for
StrictFinitePolicy
and implementations ofFpChecks
are provided forf64
andnum::Complex<f64>
. When the “rug” feature is enabled, support extends torug::Float
,rug::Complex
, and indirectly to the wrapper typesRealRugStrictFinite
andComplexRugStrictFinite
(which utilize these underlyingrug
types).
The goal of this module is to ensure numerical stability and correctness by allowing functions to easily validate their inputs and outputs according to defined policies, and to provide a common interface for basic floating-point characteristic checks.
§Enhanced Type Safety with GuaranteesFiniteValues
One of the key innovations of this validation framework is the GuaranteesFiniteValues
marker trait. This trait enables compile-time verification that a validation policy
ensures all validated values are finite, which unlocks additional type system guarantees:
- Full Equality: These types implement
Eq
, making equality comparisons well-defined and symmetric. - Hashing Support: With both
Eq
andHash
implemented, these types can be used as keys in hash-based collections likeHashMap
andHashSet
.
Note on Ordering: The library intentionally does NOT implement Ord
even for finite-guaranteed types, as our custom Max
and Min
traits provide more efficient reference-based
operations compared to Ord
’s value-based interface.
Currently, StrictFinitePolicy
and DebugValidationPolicy<StrictFinitePolicy>
implement this marker trait.
§Usage Examples
§Basic Validation
use num_valid::validation::{StrictFinitePolicy, ErrorsValidationRawReal};
use try_create::ValidationPolicy; // For the validate() method
// Valid finite number
assert!(StrictFinitePolicy::<f64, 53>::validate(1.0).is_ok());
// Invalid: NaN
let result = StrictFinitePolicy::<f64, 53>::validate(f64::NAN);
assert!(matches!(result, Err(ErrorsValidationRawReal::IsNaN { .. })));
// Invalid: Infinity
let result = StrictFinitePolicy::<f64, 53>::validate(f64::INFINITY);
assert!(matches!(result, Err(ErrorsValidationRawReal::IsPosInfinity { .. })));
// Invalid: Subnormal
let subnormal_val = f64::from_bits(1); // Smallest positive subnormal f64
let result = StrictFinitePolicy::<f64, 53>::validate(subnormal_val);
assert!(matches!(result, Err(ErrorsValidationRawReal::IsSubnormal { .. })));
§Using FpChecks
use num_valid::validation::FpChecks;
use num::Complex;
let val_f64 = 1.0f64;
let nan_f64 = f64::NAN;
let inf_f64 = f64::INFINITY;
assert!(val_f64.is_finite());
assert!(val_f64.is_normal());
assert!(nan_f64.is_nan());
assert!(!nan_f64.is_finite());
assert!(inf_f64.is_infinite());
let val_complex = Complex::new(1.0, 2.0);
let nan_complex_real = Complex::new(f64::NAN, 2.0);
let inf_complex_imag = Complex::new(1.0, f64::NEG_INFINITY);
assert!(val_complex.is_finite());
assert!(val_complex.is_normal());
assert!(nan_complex_real.is_nan());
assert!(!nan_complex_real.is_finite());
assert!(inf_complex_imag.is_infinite());
assert!(!inf_complex_imag.is_finite());
assert!(!inf_complex_imag.is_nan());
§HashMap Usage with Finite Guarantees
use num_valid::kernels::native64_validated::RealNative64StrictFinite;
use std::collections::HashMap;
use try_create::TryNew;
let mut scores = HashMap::new();
let player1 = RealNative64StrictFinite::try_new(1.5).unwrap();
let player2 = RealNative64StrictFinite::try_new(2.0).unwrap();
scores.insert(player1, 100); // Works because Eq + Hash are implemented
scores.insert(player2, 95);
assert_eq!(scores.len(), 2);
§Conditional Debug Validation
use num_valid::validation::{DebugValidationPolicy, Native64RawRealStrictFinitePolicy};
use try_create::ValidationPolicy;
type ConditionalPolicy = DebugValidationPolicy<Native64RawRealStrictFinitePolicy>;
let value = 42.0;
// Validates only in debug builds, no-op in release
assert!(ConditionalPolicy::validate(value).is_ok());
Structs§
- Debug
Validation Policy - A validation policy that is active only in debug builds.
- Strict
Finite Policy - A validation policy that checks for strict finiteness.
Enums§
- Errors
RawReal ToInteger - Errors
TryFromf64 - Errors that can occur when trying to convert an
f64
to another real-type scalar of typeRawReal
. - Errors
Validation RawComplex - Errors that can occur during the validation of a complex number.
- Errors
Validation RawReal - Errors that can occur during the validation of a raw real number.
Traits§
- FpChecks
- Provides a set of fundamental floating-point classification checks.
- Guarantees
Finite Values - A marker trait for validation policies that guarantee finite real values.
- Validation
Policy Complex - A marker for policies that apply to complex types.
- Validation
Policy Real - A marker for policies that apply to real types.
Functions§
- debug_
validate - Validates a value using the given policy, but only in debug builds. In release builds, this function is a no-op and should be optimized away.
Type Aliases§
- Native64
RawComplex Strict Finite Policy - A type alias for a validation policy that enforces strict finiteness for the raw
num::Complex<f64>
type. - Native64
RawReal Strict Finite Policy - A type alias for a validation policy that enforces strict finiteness for the raw
f64
type.