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 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::Sqrt;
use num::Complex;

assert_eq!(4.0_f64.try_sqrt().unwrap(), 2.0);
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();
assert!((sqrt_z.re).abs() < 1e-9 && (sqrt_z.im - 2.0).abs() < 1e-9);

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", so this trait is not object safe.

Implementations on Foreign Types§

Source §

impl Sqrt for f64

Source §

fn try_sqrt(self) -> Result<f64, <f64 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(Self::Error): If the input is invalid (e.g., negative for real sqrt, NaN, Infinity) or if the computed square root is invalid.

§Examples

use num_valid::functions::Sqrt;
use num::Complex;

assert_eq!(4.0_f64.try_sqrt().unwrap(), 2.0);
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();
assert!((sqrt_z.re).abs() < 1e-9 && (sqrt_z.im - 2.0).abs() < 1e-9);

Source §

fn sqrt(self) -> Self

Computes and returns the principal square root of self.

§Behavior

Debug Builds (#[cfg(debug_assertions)]): This method internally calls try_sqrt().unwrap(). It will panic if try_sqrt returns an Err.
Release Builds (#[cfg(not(debug_assertions))]): This method calls the underlying square root function directly (e.g., f64::sqrt). The behavior for invalid inputs (like sqrt(-1.0) for f64 returning NaN) depends on the underlying implementation.

§Panics

In debug builds, this method will panic if try_sqrt() would return an Err.

§Examples

use num_valid::functions::Sqrt;
use num::Complex;

assert_eq!(9.0_f64.sqrt(), 3.0);

// For f64, sqrt of negative is NaN in release, panics in debug with ftl's Sqrt
#[cfg(not(debug_assertions))]
assert!((-1.0_f64).sqrt().is_nan());

let z = Complex::new(0.0, 4.0); // sqrt(4i) = sqrt(2) + i*sqrt(2)
let sqrt_z = z.sqrt();
let expected_val = std::f64::consts::SQRT_2;
assert!((sqrt_z.re - expected_val).abs() < 1e-9 && (sqrt_z.im - expected_val).abs() < 1e-9);

Source §

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

Source §

impl Sqrt for Complex<f64>

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 §