Trait Reciprocal 

pub trait Reciprocal: Sized {
    type Error: Error;

    // Required methods
    fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error>;
    fn reciprocal(self) -> Self;
}

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>
• RealRugStrictFinite<PRECISION> (when the rug feature is enabled)
• ComplexRugStrictFinite<PRECISION> (when the rug feature is enabled)

Validation Policy

Implementations typically use a 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.

Required Associated Types

type Error: Error

The error type that can be returned by the try_reciprocal method.

This is typically an instantiation of ReciprocalErrors.

Required Methods

fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error>

Attempts to compute the reciprocal of self (1/self), returning a Result.

This method first validates the input self using 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.

fn reciprocal(self) -> Self

Returns the reciprocal of self (1/self).

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl Reciprocal for f64

fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error>

Attempts to compute the reciprocal of self (1/self), returning a Result.

This method first validates the input self using 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

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),
}

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

fn reciprocal(self) -> Self

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

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 }

type Error = FunctionErrors<ReciprocalInputErrors<f64>, <f64 as RawScalarTrait>::ValidationErrors>

impl Reciprocal for Complex<f64>

fn try_reciprocal(self) -> Result<Self, <Self as Reciprocal>::Error>

Attempts to compute the reciprocal of self (1/self), returning a Result.

This method first validates the input self using 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

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),
}

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

fn reciprocal(self) -> Self

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

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 }

type Error = FunctionErrors<ReciprocalInputErrors<Complex<f64>>, <Complex<f64> as RawScalarTrait>::ValidationErrors>

Implementors

impl<K: NumKernel> Reciprocal for ComplexValidated<K>

type Error = FunctionErrors<ReciprocalInputErrors<<<ComplexValidated<K> as TryNewValidated>::Policy as ValidationPolicy>::Value>, <<<ComplexValidated<K> as TryNewValidated>::Policy as ValidationPolicy>::Value as RawScalarTrait>::ValidationErrors>

impl<K: NumKernel> Reciprocal for RealValidated<K>

type Error = FunctionErrors<ReciprocalInputErrors<<<RealValidated<K> as TryNewValidated>::Policy as ValidationPolicy>::Value>, <<<RealValidated<K> as TryNewValidated>::Policy as ValidationPolicy>::Value as RawScalarTrait>::ValidationErrors>