Module validated

Expand description

Validated type aliases and kernel configurations for native 32/64-bit types.

§Validated Native Kernel Types

This module provides convenient, pre-configured type aliases for the native f32 and f64 kernels. These types wrap native real and complex values in the RealValidated and ComplexValidated structs, bundling them with specific validation policies.

These type aliases are the primary entry point for users who want to work with validated numbers that provide compile-time guarantees about their properties (e.g., finiteness).

§Policies

Two main policies are provided:

Native64StrictFinite: Enforces that all values are finite (not NaN or Infinity) in all build modes. Fallible try_* operations report validation and domain failures as Result values; their non-fallible counterparts panic on failure. This is the safest and most common choice.
Native64StrictFiniteInDebug: Also enforces finiteness, but validation checks that are performed only in debug builds. In release builds, validation is skipped for performance and operations assume valid inputs. This is for performance-critical code where the developer can guarantee the validity of inputs.

§Example

use num_valid::{*, functions::Sqrt};

// Creation succeeds because 4.0 is a valid, finite number.
let x = RealNative64StrictFinite::try_new(4.0).unwrap();

// Creation fails for non-finite numbers.
assert!(RealNative64StrictFinite::try_new(f64::NAN).is_err());

// Mathematical operations are available through traits.
let sqrt_x = x.sqrt();
assert_eq!(sqrt_x.as_raw_scalar_ref(), &2.0);

§Zero-Copy Conversions with Bytemuck

The validated types in this module implement bytemuck::CheckedBitPattern and bytemuck::NoUninit, enabling safe, zero-copy conversions between f64 byte representations and validated types. This is particularly useful for:

Interoperability with binary data formats and serialization
Performance-critical code working with byte arrays
Loading validated numbers from external data sources

The conversion automatically validates the bit pattern, rejecting invalid values (NaN, Infinity, subnormal numbers) while maintaining zero-cost performance for valid inputs:

use num_valid::*;
use bytemuck::checked::try_from_bytes;

// Valid conversion
let value = 42.0_f64;
let bytes = value.to_ne_bytes();
let validated: &RealNative64StrictFinite = try_from_bytes(&bytes).unwrap();
assert_eq!(validated.as_raw_scalar_ref(), &42.0);

// Invalid values are rejected
let nan_bytes = f64::NAN.to_ne_bytes();
assert!(try_from_bytes::<RealNative64StrictFinite>(&nan_bytes).is_err());

For comprehensive examples of valid conversions, error handling, and slice operations, see the test module in the source code.

Type Aliases§

ComplexNative32StrictFinite: A validated complex number that guarantees its inner f32 parts are finite.
ComplexNative64StrictFinite: A validated complex number that guarantees its inner f64 parts are finite.
ComplexNative64StrictFiniteInDebug: A validated complex number that checks for finiteness only in debug builds.
Native32StrictFinite: A kernel policy that enforces strict finiteness for f32 and Complex<f32> values.
Native32StrictFiniteInDebug: A kernel policy that enforces strict finiteness for f32 values only in debug builds.
Native64StrictFinite: A kernel policy that enforces strict finiteness for f64 and Complex<f64> values.
Native64StrictFiniteInDebug: A kernel policy that enforces strict finiteness for f64 values only in debug builds.
RealNative32StrictFinite: A validated real number that guarantees its inner f32 value is finite.
RealNative64StrictFinite: A validated real number that guarantees its inner f64 value is finite.
RealNative64StrictFiniteInDebug: A validated real number that checks for finiteness only in debug builds.