Trait Arg

Source

pub trait Arg: Sized {
    type Output: Sized;
    type Error: Error;

    // Required methods
    fn try_arg(self) -> Result<Self::Output, Self::Error>;
    fn arg(self) -> Self::Output;
}

Expand description

Trait for computing the argument (principal value) of a complex number.

The argument of a complex number z = x + iy is the angle φ (phi) in polar coordinates z = r(cos φ + i sin φ). It is typically computed using atan2(y, x) and lies in the interval (-π, π].

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

Required Associated Types§

Source

type Output: Sized

The return type of the principal value (or argument) function. It is always a real number.

Source

type Error: Error

The error type that can be returned by the Arg::try_arg() method.

This is typically an instantiation of ArgErrors.

Required Methods§

Source

fn try_arg(self) -> Result<Self::Output, Self::Error>

Attempts to compute the argument of self, returning a Result.

Source

fn arg(self) -> Self::Output

Returns the argument 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 Arg for Complex<f64>

Source §

fn try_arg(self) -> Result<Self::Output, Self::Error>

Attempts to compute the argument of 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 components, non-zero), it computes the argument and then validates the resulting real number using the same policy.

§Returns

Ok(Self::Output): If the input complex number is valid (finite, non-zero) and the computed argument is a valid (finite) real number.
Err(Self::Error): If the input is invalid (e.g., NaN or Infinity components, zero) or if the computed argument is invalid (e.g., NaN, Infinity).

§Examples

use num_valid::functions::Arg;
use num::Complex;
use std::f64::consts::PI;

let z = Complex::new(1.0, 1.0); // Represents 1 + i
match z.try_arg() {
    Ok(angle) => println!("Arg(1+i) = {}", angle), // Arg(1+i) = 0.785... (π/4)
    Err(e) => println!("Error: {:?}", e),
}

let zero = Complex::new(0.0, 0.0);
assert!(zero.try_arg().is_err());

let nan_val = Complex::new(f64::NAN, 1.0);
assert!(nan_val.try_arg().is_err());

Source §

fn arg(self) -> f64

Returns the argument of self.

§Behavior

Debug Builds (#[cfg(debug_assertions)]): This method internally calls try_arg().unwrap(). It will panic if the input self is invalid (e.g., NaN/Infinity components, zero) or if the computed argument is invalid.
Release Builds (#[cfg(not(debug_assertions))]): This method calls the underlying argument function directly (e.g., num::Complex::arg). The behavior for non-finite inputs or zero (like NaN propagation or specific return values like 0.0 for arg(0)) depends on the underlying implementation.

§Panics

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

§Examples

use num_valid::functions::Arg;
use num::Complex;
use std::f64::consts::PI;

let z = Complex::new(-1.0, 0.0); // Represents -1
println!("Arg(-1) = {}", z.arg()); // Arg(-1) = 3.141... (π)

let z_imag = Complex::new(0.0, 1.0); // Represents i
println!("Arg(i) = {}", z_imag.arg()); // Arg(i) = 1.570... (π/2)