num-valid 0.6.0

#![deny(rustdoc::broken_intra_doc_links)]

//! Reciprocal (multiplicative inverse) operations.
//!
//! This module provides the [`Reciprocal`] trait for computing `1/x` for validated
//! real and complex numbers.

use crate::{
    core::traits::raw::RawScalarValidate, functions::FunctionErrors, kernels::RawScalarTrait,
};
use std::backtrace::Backtrace;
use thiserror::Error;

#[cfg(debug_assertions)]
use crate::core::errors::capture_backtrace;

//------------------------------------------------------------------------------------------------
/// Errors that can occur during the input validation phase or due to special input
/// values when attempting to compute the reciprocal of a number.
///
/// This enum is used as a source for the [`Input`](FunctionErrors::Input) variant of [`ReciprocalErrors`].
/// It is generic over `RawScalar: RawScalarTrait`. The [`InvalidArgument`](ReciprocalInputErrors::InvalidArgument)
/// variant contains a `source` of type `<RawScalar as RawScalarValidate>::ValidationError`.
#[derive(Debug, Error)]
pub enum ReciprocalInputErrors<RawScalar: RawScalarTrait> {
    /// The input value is zero.
    ///
    /// This error occurs when the input value for the reciprocal computation is zero,
    /// as division by zero is undefined.
    #[error("division by zero!")]
    DivisionByZero {
        /// A captured backtrace for debugging purposes.
        backtrace: Backtrace,
    },

    /// The input value failed basic validation checks.
    ///
    /// This error occurs if the input value itself is considered invalid
    /// according to the validation policy (e.g., [`StrictFinitePolicy`](crate::core::policies::StrictFinitePolicy)),
    /// such as being NaN or Infinity, before the reciprocal calculation
    /// is attempted.
    #[error("the input value is invalid according to validation policy")]
    InvalidArgument {
        /// The underlying validation error from the input type.
        ///
        /// This provides more specific details about why the input value
        /// was considered invalid.
        #[source]
        #[backtrace]
        source: <RawScalar as RawScalarValidate>::ValidationError,
    },
}

/// A type alias for [`FunctionErrors`], specialized for errors that can occur during
/// the computation of the reciprocal of a scalar number.
///
/// This type represents the possible failures when calling [`Reciprocal::try_reciprocal()`].
/// It is generic over `RawScalar: RawScalarTrait`. This type alias wraps [`FunctionErrors`],
/// where the input error source is [`ReciprocalInputErrors<RawScalar>`] and the output
/// error source is `<RawScalar as RawScalarValidate>::ValidationError`.
///
/// # Variants
///
/// This type alias wraps [`FunctionErrors`], which has the following variants in this context:
///
/// - `Input { source: ReciprocalInputErrors<RawScalar> }`: Indicates that the input number
///   was invalid for reciprocal computation. This could be due to failing initial validation
///   (e.g., containing NaN or Infinity) or because the input was zero (division by zero).
///   The `source` field provides more specific details via [`ReciprocalInputErrors`].
///
/// - `Output { source: <RawScalar as RawScalarValidate>::ValidationError }`: Indicates that the computed
///   reciprocal value itself failed validation. This typically means the result of the
///   reciprocal operation yielded a non-finite value (NaN or Infinity). The `source` field
///   provides details, usually an instance of [`crate::core::errors::ErrorsValidationRawReal`]
///   or [`crate::core::errors::ErrorsValidationRawComplex`].
pub type ReciprocalErrors<RawScalar> = FunctionErrors<
    ReciprocalInputErrors<RawScalar>,
    <RawScalar as RawScalarValidate>::ValidationError,
>;

/// A trait for computing the reciprocal (`1/x`) of a number.
///
/// This trait provides an interface for calculating the reciprocal of a number,
/// which can be real or complex. It includes both a fallible version (`try_reciprocal`)
/// that performs validation and an infallible version (`reciprocal`) that may panic
/// in debug builds if validation fails.
///
/// # Implementors
///
/// This trait is implemented for:
/// - `f64`
/// - [`Complex<f64>`](num::Complex)
/// - `RealRugStrictFinite<PRECISION>` (when the `rug` feature is enabled)
/// - `ComplexRugStrictFinite<PRECISION>` (when the `rug` feature is enabled)
///
/// # Validation Policy
///
/// Implementations typically use a [`StrictFinitePolicy`](crate::core::policies::StrictFinitePolicy) for validating inputs and outputs.
/// This means that NaN, Infinity, and subnormal numbers (for `f64`-based types)
/// will generally result in an error or panic. Division by zero is also explicitly handled.
pub trait Reciprocal: Sized {
    /// The error type that can be returned by the `try_reciprocal` method.
    ///
    /// This is typically an instantiation of [`ReciprocalErrors`].
    type Error: std::error::Error;

    /// Attempts to compute the reciprocal of `self` (`1/self`), returning a `Result`.
    ///
    /// This method first validates the input `self` using [`StrictFinitePolicy`](crate::core::policies::StrictFinitePolicy) and
    /// also checks if it is zero. If the input is valid (finite, non-zero, normal),
    /// it computes the reciprocal and then validates the result using the same policy.
    #[must_use = "this `Result` may contain an error that should be handled"]
    fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error>;

    /// Returns the reciprocal of `self` (`1/self`).
    fn reciprocal(self) -> Self;
}

impl<T> Reciprocal for T
where
    T: RawScalarTrait,
{
    type Error = ReciprocalErrors<Self>;

    /// Attempts to compute the reciprocal of `self` (`1/self`), returning a `Result`.
    ///
    /// This method first validates the input `self` using [`StrictFinitePolicy`](crate::core::policies::StrictFinitePolicy) and
    /// also checks if it is zero. If the input is valid (finite, non-zero, normal),
    /// it computes the reciprocal and then validates the result using the same policy.
    ///
    /// # Returns
    ///
    /// - `Ok(Self)`: If both the input and the computed reciprocal are valid.
    /// - `Err(Self::Error)`: If the input is invalid (e.g., NaN, Infinity, zero, subnormal)
    ///   or if the computed reciprocal is invalid (e.g., NaN, Infinity, overflow).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use num_valid::{ComplexScalar, functions::{ComplexScalarConstructors, Reciprocal}};
    /// use num::Complex;
    /// use try_create::TryNew;
    ///
    /// // For f64
    /// let x = 4.0_f64;
    /// match x.try_reciprocal() {
    ///     Ok(val) => println!("1/{} = {}", x, val), // 1/4.0 = 0.25
    ///     Err(e) => println!("Error: {:?}", e),
    /// }
    ///
    /// #[cfg(debug_assertions)]
    /// {
    ///     assert!(0.0_f64.try_reciprocal().is_err());
    ///     assert!(f64::NAN.try_reciprocal().is_err());
    /// }
    ///
    /// // For Complex<f64>
    /// let z = Complex::new(2.0, 0.0);
    /// assert_eq!(z.try_reciprocal().unwrap(), Complex::try_new_pure_real(0.5).unwrap());
    /// ```
    #[inline(always)]
    fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error> {
        #[cfg(debug_assertions)]
        {
            self.validate_raw_scalar()
                .map_err(|e| ReciprocalInputErrors::InvalidArgument { source: e }.into())
                .and_then(|value| {
                    if value.is_zero() {
                        Err(ReciprocalInputErrors::DivisionByZero {
                            backtrace: capture_backtrace(),
                        }
                        .into())
                    } else {
                        // value is different from zero, so we can "safely" compute the reciprocal
                        value
                            .unchecked_reciprocal()
                            .validate_raw_scalar()
                            .map_err(|e| ReciprocalErrors::<Self>::Output { source: e })
                    }
                })
        }
        #[cfg(not(debug_assertions))]
        {
            // In release builds, we skip validation and directly compute the reciprocal.
            // The behavior for non-finite inputs or division by zero (like NaN propagation or
            // overflow resulting in Infinity) depends on the underlying implementation for the specific type.
            Ok(self.unchecked_reciprocal())
        }
    }

    /// Returns the reciprocal of `self` (`1/self`).
    ///
    /// # Behavior
    ///
    /// - **Debug Builds (`#[cfg(debug_assertions)]`)**: This method internally calls `try_reciprocal().unwrap()`.
    ///   It will panic if the input `self` is invalid (e.g., NaN, Infinity, zero, subnormal)
    ///   or if the computed reciprocal is invalid.
    /// - **Release Builds (`#[cfg(not(debug_assertions))]`)**: This method calls the underlying
    ///   reciprocal function directly (e.g., `1.0 / x` for `f64`, `num::Complex::inv`).
    ///   The behavior for non-finite inputs or division by zero (like NaN propagation or
    ///   overflow resulting in Infinity) depends on the underlying implementation for the specific type.
    ///
    /// # Panics
    ///
    /// In debug builds, this method will panic if `try_reciprocal()` would return an `Err`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use num_valid::functions::Reciprocal;
    /// use num::Complex;
    ///
    /// let x = 2.0_f64;
    /// println!("1/{} = {}", x, x.reciprocal()); // 1/2.0 = 0.5
    ///
    /// let z = Complex::new(0.0, -4.0); // 1 / (-4i) = i/4 = 0.25i
    /// println!("1/({:?}) = {:?}", z, z.reciprocal()); // 1/Complex { re: 0.0, im: -4.0 } = Complex { re: 0.0, im: 0.25 }
    /// ```
    #[inline(always)]
    fn reciprocal(self) -> Self {
        #[cfg(debug_assertions)]
        {
            self.try_reciprocal().unwrap()
        }
        #[cfg(not(debug_assertions))]
        {
            self.unchecked_reciprocal()
        }
    }
}

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

//------------------------------------------------------------------------------------------------
#[cfg(test)]
mod tests {
    use super::*;
    use num::Complex;

    #[cfg(debug_assertions)]
    use std::assert_matches;

    #[cfg(debug_assertions)]
    use crate::core::errors::{ErrorsValidationRawComplex, ErrorsValidationRawReal};

    #[cfg(feature = "rug")]
    use try_create::TryNew;

    mod reciprocal {
        use super::*;
        mod native {
            use super::*;

            mod real {
                use super::*;

                #[test]
                fn test_f64_reciprocal_valid() {
                    let value = 4.0;
                    assert_eq!(value.try_reciprocal().unwrap(), 0.25);
                    assert_eq!(value.reciprocal(), 0.25);
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_f64_reciprocal_zero() {
                    let value = 0.0;
                    let result = value.try_reciprocal();
                    assert!(matches!(
                        result,
                        Err(ReciprocalErrors::<f64>::Input(
                            ReciprocalInputErrors::DivisionByZero { .. }
                        ))
                    ));
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_f64_reciprocal_nan() {
                    let value = f64::NAN;
                    let result = value.try_reciprocal();
                    assert!(matches!(
                        result,
                        Err(ReciprocalErrors::<f64>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawReal::IsNaN { .. }
                            }
                        ))
                    ));
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_f64_reciprocal_subnormal() {
                    let value = f64::MIN_POSITIVE / 2.0;
                    let result = value.try_reciprocal();
                    assert!(matches!(
                        result,
                        Err(ReciprocalErrors::<f64>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawReal::IsSubnormal { .. }
                            }
                        ))
                    ));
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_f64_reciprocal_infinite() {
                    let value = f64::INFINITY;
                    let result = value.try_reciprocal();
                    assert!(matches!(
                        result,
                        Err(ReciprocalErrors::<f64>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawReal::IsPosInfinity { .. }
                            }
                        ))
                    ));
                }
            }

            mod complex {
                use super::*;

                #[test]
                fn test_complex_f64_reciprocal_valid() {
                    let value = Complex::new(4.0, 0.0);
                    assert_eq!(value.try_reciprocal().unwrap(), Complex::new(0.25, 0.0));
                    assert_eq!(value.reciprocal(), Complex::new(0.25, 0.0));
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_complex_f64_reciprocal_zero() {
                    let value = Complex::new(0.0, 0.0);
                    let result = value.try_reciprocal();
                    assert!(matches!(
                        result,
                        Err(ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::DivisionByZero { .. }
                        ))
                    ));
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_complex_f64_reciprocal_nan() {
                    let value = Complex::new(f64::NAN, 0.0);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidRealPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsNaN { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }

                    let value = Complex::new(0.0, f64::NAN);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidImaginaryPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsNaN { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_complex_f64_reciprocal_infinite() {
                    let value = Complex::new(f64::INFINITY, 0.0);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidRealPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsPosInfinity { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }

                    let value = Complex::new(0.0, f64::INFINITY);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidImaginaryPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsPosInfinity { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }
                }

                #[test]
                #[cfg(debug_assertions)]
                fn test_complex_f64_reciprocal_sbnormal() {
                    let value = Complex::new(f64::MIN_POSITIVE / 2.0, 0.0);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidRealPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsSubnormal { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }

                    let value = Complex::new(0.0, f64::MIN_POSITIVE / 2.0);
                    let err = value.try_reciprocal().unwrap_err();
                    match err {
                        ReciprocalErrors::<Complex<f64>>::Input(
                            ReciprocalInputErrors::InvalidArgument {
                                source: ErrorsValidationRawComplex::InvalidImaginaryPart { source },
                            },
                        ) => {
                            assert_matches!(*source, ErrorsValidationRawReal::IsSubnormal { .. });
                        }
                        _ => {
                            unreachable!();
                        }
                    }
                }
            }

            #[cfg(feature = "rug")]
            mod rug53 {
                use super::*;
                use crate::backends::rug::validated::{
                    ComplexRugStrictFinite, RealRugStrictFinite,
                };

                mod real {
                    use super::*;

                    #[test]
                    fn test_rug_float_reciprocal_valid() {
                        let value =
                            RealRugStrictFinite::<53>::try_new(rug::Float::with_val(53, 4.0))
                                .unwrap();
                        let result = value.try_reciprocal();
                        assert!(result.is_ok());
                    }

                    #[test]
                    fn test_rug_float_reciprocal_zero() {
                        let value =
                            RealRugStrictFinite::<53>::try_new(rug::Float::with_val(53, 0.0))
                                .unwrap();
                        let result = value.try_reciprocal();
                        assert!(matches!(
                            result,
                            Err(ReciprocalErrors::Input(
                                ReciprocalInputErrors::DivisionByZero { .. }
                            ))
                        ));
                    }
                }

                mod complex {
                    use super::*;

                    #[test]
                    fn test_complex_rug_float_reciprocal_valid() {
                        let value = ComplexRugStrictFinite::<53>::try_new(rug::Complex::with_val(
                            53,
                            (rug::Float::with_val(53, 4.0), rug::Float::with_val(53, 0.0)),
                        ))
                        .unwrap();

                        let expected_result =
                            ComplexRugStrictFinite::<53>::try_new(rug::Complex::with_val(
                                53,
                                (
                                    rug::Float::with_val(53, 0.25),
                                    rug::Float::with_val(53, 0.0),
                                ),
                            ))
                            .unwrap();

                        assert_eq!(value.clone().try_reciprocal().unwrap(), expected_result);
                        assert_eq!(value.reciprocal(), expected_result);
                    }

                    #[test]
                    fn test_complex_rug_float_reciprocal_zero() {
                        let value = ComplexRugStrictFinite::<53>::try_new(rug::Complex::with_val(
                            53,
                            (rug::Float::with_val(53, 0.0), rug::Float::with_val(53, 0.0)),
                        ))
                        .unwrap();
                        assert!(matches!(
                            value.try_reciprocal(),
                            Err(ReciprocalErrors::Input(
                                ReciprocalInputErrors::DivisionByZero { .. }
                            ))
                        ));
                    }
                }
            }
        }
    }
}
//------------------------------------------------------------------------------------------------