ftl-numkernel 0.1.0

#![deny(rustdoc::broken_intra_doc_links)]

//! This module defines error types and traits for validating real and complex values.
//!
//! The module provides:
//! - [`RealValueErrors`]: An enum representing errors that can occur during the validation of real (floating point) numbers.
//! - [`ComplexValueErrors`]: An enum representing errors that can occur during the validation of complex numbers.
//! - [`RealValueValidator`]: A trait for validating real values.
//! - [`ComplexValueValidator`]: A trait for validating complex values.

use num::Complex;
use std::{backtrace::Backtrace, num::FpCategory};
use thiserror::Error;

//-------------------------------------------------------------
/// Errors that can be generated from the validation of a real (floating point) number.
#[derive(Debug, Error)]
pub enum RealValueErrors<RealType> {
    /// The value is infinite.
    ///
    /// This error occurs when the value being validated is infinite.
    #[error("the value is infinite!")]
    Infinite {
        /// The backtrace of the error.
        backtrace: Backtrace,
    },

    /// The value is NaN (Not a Number).
    ///
    /// This error occurs when the value being validated is NaN (Not a Number).
    #[error("the value is NaN!")]
    NaN {
        /// The backtrace of the error.
        backtrace: Backtrace,
    },

    /// The value is [subnormal](https://en.wikipedia.org/wiki/Subnormal_number).
    ///
    /// This error occurs when the value being validated is subnormal.
    #[error("the value ({value:?}) is subnormal!")]
    Subnormal {
        /// The subnormal value.
        value: RealType,

        /// The backtrace of the error.
        backtrace: Backtrace,
    },
}

/// Errors that can be generated from the validation of a complex number.
#[derive(Debug, Error)]
pub enum ComplexValueErrors<RealType, ComplexType> {
    /// The real part is invalid.
    ///
    /// This error occurs when the real part of the complex number is invalid.
    #[error("the value ({value:?}) has an invalid real part!")]
    InvalidRealPart {
        /// The complex value that caused the error.
        value: ComplexType,

        /// The error that occurred while validating the real part.
        #[source]
        #[backtrace]
        real_part_error: RealValueErrors<RealType>,
    },

    /// The imaginary part is invalid.
    ///
    /// This error occurs when the imaginary part of the complex number is invalid.
    #[error("the value ({value:?}) has an invalid imaginary part!")]
    InvalidImaginaryPart {
        /// The complex value that caused the error.
        value: ComplexType,

        /// The error that occurred while validating the imaginary part.
        #[source]
        #[backtrace]
        imaginary_part_error: RealValueErrors<RealType>,
    },
}
//-------------------------------------------------------------

//-------------------------------------------------------------
/// A trait for validating real values.
///
/// This trait provides a method for validating real values, ensuring that they
/// are not infinite, NaN, or subnormal. If the value is valid, it returns `Ok(self)`.
/// Otherwise, it returns an appropriate error variant of `RealValueErrors`.
pub trait RealValueValidator: Sized {
    /// Validates the real value.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., it is not infinite, NaN, or subnormal).
    /// * `Err(RealValueErrors::Infinite)` if the value is infinite.
    /// * `Err(RealValueErrors::NaN)` if the value is NaN.
    /// * `Err(RealValueErrors::Subnormal)` if the value is subnormal.
    fn validate(self) -> Result<Self, RealValueErrors<Self>>;
}

impl RealValueValidator for f64 {
    /// Validates the `f64` value.
    ///
    /// This implementation checks the floating-point category of the value and
    /// returns an appropriate error if the value is infinite, NaN, or subnormal.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., it is not infinite, NaN, or subnormal).
    /// * `Err(RealValueErrors::Infinite)` if the value is infinite.
    /// * `Err(RealValueErrors::NaN)` if the value is NaN.
    /// * `Err(RealValueErrors::Subnormal)` if the value is subnormal.
    fn validate(self) -> Result<Self, RealValueErrors<Self>> {
        let fp_type = self.classify();
        match fp_type {
            FpCategory::Infinite => Err(RealValueErrors::Infinite {
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Nan => Err(RealValueErrors::NaN {
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Subnormal => Err(RealValueErrors::Subnormal {
                value: self,
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Zero | FpCategory::Normal => Ok(self),
        }
    }
}

#[cfg(feature = "rug")]
impl RealValueValidator for rug::Float {
    /// Validates the `rug::Float` value.
    ///
    /// This implementation checks the floating-point category of the value and
    /// returns an appropriate error if the value is infinite, NaN, or subnormal.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., it is not infinite, NaN, or subnormal).
    /// * `Err(RealValueErrors::Infinite)` if the value is infinite.
    /// * `Err(RealValueErrors::NaN)` if the value is NaN.
    /// * `Err(RealValueErrors::Subnormal)` if the value is subnormal.
    fn validate(self) -> Result<Self, RealValueErrors<Self>> {
        let fp_type = self.classify();
        match fp_type {
            FpCategory::Infinite => Err(RealValueErrors::Infinite {
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Nan => Err(RealValueErrors::NaN {
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Subnormal => Err(RealValueErrors::Subnormal {
                value: self,
                backtrace: Backtrace::force_capture(),
            }),
            FpCategory::Zero | FpCategory::Normal => Ok(self),
        }
    }
}
//-------------------------------------------------------------

//-------------------------------------------------------------
/// A trait for validating complex values.
///
/// This trait provides a method for validating complex values, ensuring that their
/// real and imaginary parts are not infinite, NaN, or subnormal. If the value is valid,
/// it returns `Ok(self)`. Otherwise, it returns an appropriate error variant of `ComplexValueErrors`.
pub trait ComplexValueValidator: Sized {
    type RealType: Sized;

    /// Validates the complex value.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., both the real and imaginary parts are not infinite, NaN, or subnormal).
    /// * `Err(ComplexValueErrors::InvalidRealPart)` if the real part is invalid.
    /// * `Err(ComplexValueErrors::InvalidImaginaryPart)` if the imaginary part is invalid.
    fn validate(self) -> Result<Self, ComplexValueErrors<Self::RealType, Self>>;
}

impl ComplexValueValidator for Complex<f64> {
    type RealType = f64;

    /// Validates the `Complex<f64>` value.
    ///
    /// This implementation checks the floating-point category of the real and imaginary parts
    /// of the complex value and returns an appropriate error if either part is infinite, NaN, or subnormal.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., both the real and imaginary parts are not infinite, NaN, or subnormal).
    /// * `Err(ComplexValueErrors::InvalidRealPart)` if the real part is invalid.
    /// * `Err(ComplexValueErrors::InvalidImaginaryPart)` if the imaginary part is invalid.
    fn validate(self) -> Result<Self, ComplexValueErrors<Self::RealType, Self>> {
        let real_part = match self.re.validate() {
            Ok(real_part) => real_part,
            Err(real_part_error) => {
                return Err(ComplexValueErrors::InvalidRealPart {
                    value: self,
                    real_part_error,
                })
            }
        };
        let imaginary_part = match self.im.validate() {
            Ok(imaginary_part) => imaginary_part,
            Err(imaginary_part_error) => {
                return Err(ComplexValueErrors::InvalidImaginaryPart {
                    value: self,
                    imaginary_part_error,
                })
            }
        };
        Ok(Self {
            re: real_part,
            im: imaginary_part,
        })
    }
}

#[cfg(feature = "rug")]
impl ComplexValueValidator for rug::Complex {
    type RealType = rug::Float;

    /// Validates the `rug::Complex` value.
    ///
    /// This implementation checks the floating-point category of the real and imaginary parts
    /// of the complex value and returns an appropriate error if either part is infinite, NaN, or subnormal.
    ///
    /// # Returns
    ///
    /// * `Ok(self)` if the value is valid (i.e., both the real and imaginary parts are not infinite, NaN, or subnormal).
    /// * `Err(ComplexValueErrors::InvalidRealPart)` if the real part is invalid.
    /// * `Err(ComplexValueErrors::InvalidImaginaryPart)` if the imaginary part is invalid.
    fn validate(self) -> Result<Self, ComplexValueErrors<Self::RealType, Self>> {
        let (re, im) = self.clone().into_real_imag();

        let _real_part = match re.validate() {
            Ok(real_part) => real_part,
            Err(real_part_error) => {
                return Err(ComplexValueErrors::InvalidRealPart {
                    value: self,
                    real_part_error,
                })
            }
        };
        let _imaginary_part = match im.validate() {
            Ok(imaginary_part) => imaginary_part,
            Err(imaginary_part_error) => {
                return Err(ComplexValueErrors::InvalidImaginaryPart {
                    value: self,
                    imaginary_part_error,
                })
            }
        };
        Ok(self)
    }
}
//-------------------------------------------------------------

//-------------------------------------------------------------
/// Errors that can be generated by the conversion from a `f64` value.
#[derive(Debug, Error)]
pub enum TryFromf64Errors {
    /// The input value is invalid.
    ///
    /// This error occurs when the input value being converted is invalid.
    #[error("the input value is invalid!")]
    ValidationError {
        /// The source error that occurred during validation.
        #[from]
        source: RealValueErrors<f64>,
    },

    /// The input `value` is not representable exactly with the asked `precision`.
    ///
    /// This error occurs when the input `f64` value cannot be exactly represented with the specified precision.
    #[error("the input f64 value ({value:?}) cannot be exactly represented with the specific precision ({precision:?}). Try to increase the precision.")]
    NonRepresentableExactly {
        /// The input `f64` value.
        value: f64,

        /// The precision that was requested.
        precision: u32,

        /// The backtrace of the error.
        backtrace: Backtrace,
    },
}

// Conditional compilation for the `rug` feature
#[cfg(feature = "rug")]
/// Errors that can be generated by the conversion from a `rug::Float` value.
#[derive(Debug, Error)]
pub enum TryFromRugFloatErrors {
    /// The input value is invalid.
    ///
    /// This error occurs when the input value being converted is invalid.
    #[error("the input value is invalid!")]
    ValidationError {
        /// The source error that occurred during validation.
        #[from]
        source: RealValueErrors<f64>,
    },

    /// The input `value` is not representable exactly with the asked precision.
    ///
    /// This error occurs when the input `rug::Float` value cannot be exactly represented with the specified precision.
    #[error("the input rug::Float value ({value:?}) has a precision of {precision_in:?} and cannot be exactly represented with the specific asked precision ({precision_asked:?}). The input value is approximated to ({value_approx:?}). Try to increase the precision.")]
    NonRepresentableExactly {
        /// The input `rug::Float` value.
        value: rug::Float,

        /// The precision of the input value.
        precision_in: u32,

        /// The precision that was requested.
        precision_asked: u32,

        /// The approximated value.
        value_approx: rug::Float,

        /// The backtrace of the error.
        backtrace: Backtrace,
    },
}
//-------------------------------------------------------------

//-------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    mod native64 {
        use super::*;

        mod real {
            use super::*;

            #[test]
            fn test_f64_validate_infinite() {
                let value = f64::INFINITY;
                let result = value.validate();
                assert!(matches!(result, Err(RealValueErrors::Infinite { .. })));
            }

            #[test]
            fn test_f64_validate_nan() {
                let value = f64::NAN;
                let result = value.validate();
                assert!(matches!(result, Err(RealValueErrors::NaN { .. })));
            }

            #[test]
            fn test_f64_validate_subnormal() {
                let value = f64::MIN_POSITIVE / 2.0;
                let result = value.validate();
                assert!(matches!(result, Err(RealValueErrors::Subnormal { .. })));
            }

            #[test]
            fn test_f64_validate_zero() {
                let value = 0.0;
                let result = value.validate();
                assert!(matches!(result, Ok(0.0)));
            }

            #[test]
            fn test_f64_validate_normal() {
                let value = 1.0;
                let result = value.validate();
                assert!(matches!(result, Ok(1.0)));
            }
        }

        mod complex {
            use super::*;

            #[test]
            fn test_complex_f64_validate_invalid_real_part() {
                let value = Complex::new(f64::INFINITY, 1.0);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidRealPart { .. })
                ));

                let value = Complex::new(f64::NAN, 1.0);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidRealPart { .. })
                ));

                let value = Complex::new(f64::MIN_POSITIVE / 2.0, 1.0);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidRealPart { .. })
                ));
            }

            #[test]
            fn test_complex_f64_validate_invalid_imaginary_part() {
                let value = Complex::new(1.0, f64::INFINITY);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidImaginaryPart { .. })
                ));

                let value = Complex::new(1.0, f64::NAN);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidImaginaryPart { .. })
                ));

                let value = Complex::new(1.0, f64::MIN_POSITIVE / 2.0);
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidImaginaryPart { .. })
                ));
            }

            #[test]
            fn test_complex_f64_validate_zero() {
                let value = Complex::new(0.0, 0.0);
                let result = value.validate();
                assert!(matches!(result, Ok(_)));
            }

            #[test]
            fn test_complex_f64_validate_normal() {
                let value = Complex::new(1.0, 1.0);
                let result = value.validate();
                assert!(matches!(result, Ok(_)));
            }
        }
    }

    #[cfg(feature = "rug")]
    mod rug53 {
        use super::*;
        use rug::Float;

        mod real {
            use super::*;

            #[test]
            fn test_rug_float_validate_infinite() {
                let value = Float::with_val(53, f64::INFINITY);
                let result = value.validate();
                assert!(matches!(result, Err(RealValueErrors::Infinite { .. })));
            }

            #[test]
            fn test_rug_float_validate_nan() {
                let value = Float::with_val(53, f64::NAN);
                let result = value.validate();
                assert!(matches!(result, Err(RealValueErrors::NaN { .. })));
            }

            #[test]
            fn test_rug_float_validate_subnormal() {
                let value = Float::with_val(53, f64::MIN_POSITIVE);
                println!("value: {:?}", value);
                let value = Float::with_val(53, f64::MIN_POSITIVE / 2.0);
                println!("value: {:?}", value);
                let result = value.validate();
                println!("result: {:?}", result);
                //        assert!(matches!(result, Err(RealValueErrors::Subnormal { .. })));

                // rug::Float is never subnormal
                assert!(matches!(result, Ok(..)));
            }

            #[test]
            fn test_rug_float_validate_zero() {
                let value = Float::with_val(53, 0.0);
                let result = value.validate();
                assert!(matches!(result, Ok(_)));
            }

            #[test]
            fn test_rug_float_validate_normal() {
                let value = Float::with_val(53, 1.0);
                let result = value.validate();
                assert!(matches!(result, Ok(_)));
            }
        }

        mod complex {
            use super::*;
            use rug::Complex;

            #[test]
            fn test_complex_rug_float_validate_invalid_real_part() {
                let value = Complex::with_val(
                    53,
                    (Float::with_val(53, f64::INFINITY), Float::with_val(53, 1.0)),
                );
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidRealPart { .. })
                ));

                let value = Complex::with_val(
                    53,
                    (Float::with_val(53, f64::NAN), Float::with_val(53, 1.0)),
                );
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidRealPart { .. })
                ));

                let value = Complex::with_val(
                    53,
                    (
                        Float::with_val(53, f64::MIN_POSITIVE / 2.0),
                        Float::with_val(53, 1.0),
                    ),
                );
                let result = value.validate();
                // rug::Float is never subnormal
                assert!(matches!(result, Ok(_)));
            }

            #[test]
            fn test_complex_rug_float_validate_invalid_imaginary_part() {
                let value = Complex::with_val(
                    53,
                    (Float::with_val(53, 1.0), Float::with_val(53, f64::INFINITY)),
                );
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidImaginaryPart { .. })
                ));

                let value = Complex::with_val(
                    53,
                    (Float::with_val(53, 1.0), Float::with_val(53, f64::NAN)),
                );
                let result = value.validate();
                assert!(matches!(
                    result,
                    Err(ComplexValueErrors::InvalidImaginaryPart { .. })
                ));

                let value = Complex::with_val(
                    53,
                    (
                        Float::with_val(53, 1.0),
                        Float::with_val(53, f64::MIN_POSITIVE / 2.0),
                    ),
                );
                let result = value.validate();
                // rug::Float is never subnormal
                assert!(matches!(result, Ok(_)));
            }

            #[test]
            fn test_complex_rug_float_validate_zero() {
                let zero =
                    Complex::with_val(53, (Float::with_val(53, 0.0), Float::with_val(53, 0.0)));
                let result = zero.validate();
                assert!(matches!(result, Ok(_)));
            }

            #[test]
            fn test_complex_rug_float_validate_normal() {
                let value =
                    Complex::with_val(53, (Float::with_val(53, 1.0), Float::with_val(53, 1.0)));
                let result = value.validate();
                assert!(matches!(result, Ok(_)));
            }
        }
    }
}