Module native64_validated

Expand description

§Validated Native 64-bit Kernel Types

This module provides convenient, pre-configured type aliases for the native f64 kernel. These types wrap f64 and num::Complex<f64> 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. Operations on types using this policy will panic on validation failure in debug builds and return a Result in release builds. This is the safest and most common choice.
Native64StrictFiniteInDebug: Also enforces finiteness, but validation checks that would panic are only performed in debug builds. In release builds, these checks are skipped for performance, and operations assume the inputs are valid. This is for performance-critical code where the developer can guarantee the validity of inputs.

§Example

use num_valid::kernels::native64_validated::RealNative64StrictFinite;
use num_valid::functions::Sqrt;
use try_create::TryNew;

// 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_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::RealNative64StrictFinite;
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_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§

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.
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.
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.