Trait Sqrt

Source

pub trait Sqrt: Sized {
    type Error: Debug;

    // Required methods
    fn try_sqrt(self) -> Result<Self, <Self as Sqrt>::Error>;
    fn sqrt(self) -> Self;
}

Expand description

A trait for computing the principal square root of a number.

The principal square root of a non-negative real number x is the unique non-negative real number y such that y^2 = x. For a complex number z, its square root w satisfies w^2 = z. Complex numbers (except 0) have two square roots; this trait computes the principal square root, typically defined as exp(0.5 * log(z)), which usually has a non-negative real part.

This trait provides both a fallible version (try_sqrt) that performs validation in debug builds and an infallible version (sqrt) that may panic in debug builds if validation fails.

Required Associated Types§

Source

type Error: Debug

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

Required Methods§

Source

fn try_sqrt(self) -> Result<Self, <Self as Sqrt>::Error>

Attempts to compute the principal square root of self, returning a Result.

Implementations should validate the input self according to the domain (e.g., non-negative for reals) and a general validation policy (e.g., StrictFinitePolicy). If the input is valid, the square root is computed, and then the result is also validated using the same policy.

§Returns

Ok(Self): If the input is valid for the square root operation and both the input and the computed square root satisfy the validation policy.
Err(SqrtRealErrors): If the input is invalid (e.g., negative for real sqrt, NaN, Infinity) or if the computed square root is invalid (see below).

§Errors

Returns SqrtRealErrors::Input (for reals) or SqrtComplexErrors::Input (for complex) via FunctionErrors::Input if the input is invalid (e.g., negative real, NaN, Infinity, subnormal).
Returns SqrtRealErrors::Output or SqrtComplexErrors::Output via FunctionErrors::Output if the result of the computation is not finite (e.g., NaN, Infinity) as per the validation policy.

§Examples

use num_valid::{*, functions::{Abs, Sqrt}};
use num::Complex;

assert_eq!(4.0_f64.try_sqrt().unwrap(), 2.0);
#[cfg(debug_assertions)]
{
    assert!((-1.0_f64).try_sqrt().is_err()); // Negative real
    assert!(f64::NAN.try_sqrt().is_err());
}

let z = Complex::new(-4.0, 0.0); // sqrt(-4) = 2i
let sqrt_z = z.try_sqrt().unwrap();

let tol = 1e-9;
assert!(<f64 as Abs>::abs(sqrt_z.re).as_raw_scalar_ref() < &tol &&
    <f64 as Abs>::abs(sqrt_z.im - 2.0).as_raw_scalar_ref() < &tol);

Source

fn sqrt(self) -> Self

Computes the square principal square root of self.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types§

Source §

impl<T> Sqrt for Complex<T>
where Self: RawComplexTrait<RawReal = T>, T: NativeReal,

Source §

fn try_sqrt(self) -> Result<Self, <Self as Sqrt>::Error>

Attempts to compute the principal square root of self (a Complex<f64>).

This method first validates self using StrictFinitePolicy (components must be finite and normal). If valid, it computes Complex::sqrt and validates the result using StrictFinitePolicy.

§Returns

Ok(Complex<f64>): If self and the computed square root have finite and normal components.
Err(SqrtComplexErrors<Complex<f64>>): If self or the result has invalid components.

Source §