Module validation 

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, and ErrorsTryFromf64. These errors detail various validation failures like non-finite values, subnormal numbers (for f64 and rug::Float), and precision mismatches for rug types.
• Validation Policies: Implemented via the ValidationPolicy trait from the try_create crate. The primary policy provided is StrictFinitePolicy, which ensures that numbers are finite (not NaN or Infinity) and, for f64 and rug::Float, not subnormal.
• Floating-Point Checks Trait: The FpChecks trait, defined within this module, provides common classification methods like is_finite, is_nan, is_infinite, and is_normal. This trait is implemented for standard and rug-based scalar types.
• Implementations: Validation logic for StrictFinitePolicy and implementations of FpChecks are provided for f64, num::Complex<f64>. When the “rug” feature is enabled, support extends to rug::Float, rug::Complex, and indirectly to the wrapper types RealRugStrictFinite and ComplexRugStrictFinite (which utilize these underlying rug 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.

Example: Using StrictFinitePolicy

use num_valid::validation::{StrictFinitePolicy, ErrorsValidationRawReal};
use try_create::ValidationPolicy; // For the validate method

let finite_val = 10.0f64;
let nan_val = f64::NAN;
let subnormal_val = f64::from_bits(1); // Smallest positive subnormal f64

assert!(StrictFinitePolicy::<f64, 53>::validate(finite_val).is_ok());

let nan_validation_result = StrictFinitePolicy::<f64, 53>::validate(nan_val);
assert!(nan_validation_result.is_err());
if let Err(ErrorsValidationRawReal::IsNaN { value, .. }) = nan_validation_result {
    assert!(value.is_nan());
} else {
    panic!("Expected NaN error for f64::NAN");
}

let subnormal_validation_result = StrictFinitePolicy::<f64, 53>::validate(subnormal_val);
assert!(subnormal_validation_result.is_err());
if let Err(ErrorsValidationRawReal::IsSubnormal { value, .. }) = subnormal_validation_result {
    assert_eq!(value, subnormal_val);
} else {
    panic!("Expected Subnormal error for subnormal f64");
}

Example: 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());

Structs

DebugValidationPolicy

A validation policy that is active only in debug builds.

StrictFinitePolicy

A validation policy that checks for strict finiteness.

Enums

ErrorsTryFromf64

Errors that can occur when trying to convert an f64 to another real-type scalar of type RawReal.

ErrorsValidationRawComplex

Errors that can occur during the validation of a complex number.

ErrorsValidationRawReal

Errors that can occur during the validation of a raw real number.

Traits

FpChecks

Provides a set of fundamental floating-point classification checks.

ValidationPolicyComplex

A marker for policies that apply to complex types.

ValidationPolicyReal

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

Native64RawComplexStrictFinitePolicy

A type alias for a validation policy that enforces strict finiteness for the raw num::Complex<f64> type.

Native64RawRealStrictFinitePolicy

A type alias for a validation policy that enforces strict finiteness for the raw f64 type.