Trait ATan2

Source

pub trait ATan2: Sized {
    type Error: Error;

    // Required methods
    fn try_atan2(self, denominator: &Self) -> Result<Self, Self::Error>;
    fn atan2(self, denominator: &Self) -> Self;
}

Expand description

Trait for computing the 2-argument arctangent of two numbers, y (self) and x (denominator).

The atan2(y, x) function calculates the principal value of the arctangent of y/x, using the signs of both arguments to determine the correct quadrant of the result. The result is an angle in radians, typically in the range (-π, π].

This trait provides two methods:

try_atan2: A fallible version that performs validation on both inputs (numerator self and denominator x) and potentially the output. It returns a Result. This is the preferred method for robust error handling.
atan2: A convenient infallible version that panics if try_atan2 would return an error in debug builds, or directly computes the value in release builds. Use this when inputs are known to be valid or when panicking on error is acceptable.

§Associated Types

Error: The error type returned by the try_atan2 method. This type must implement std::error::Error. For f64, this is typically ATan2Errors<f64>.

§Required Methods

try_atan2(self, denominator: &Self) -> Result<Self, Self::Error>: Attempts to compute atan2(self, denominator). Validates both self (numerator) and denominator using StrictFinitePolicy. Also considers the case atan2(0, 0) as an error (ATan2InputErrors::ZeroOverZero). The output is also validated using StrictFinitePolicy.
atan2(self, denominator: &Self) -> Self: Computes atan2(self, denominator) directly. In debug builds, this calls try_atan2 and unwraps. In release builds, this typically calls the underlying standard library’s atan2 function.

§Example

use num_valid::{functions::ATan2, backends::native::raw::Native64}; // Assuming Native64 implements ATan2

let y = 1.0; // Represents the numerator
let x = 1.0; // Represents the denominator

// Using the fallible method
match y.try_atan2(&x) {
    Ok(result) => println!("atan2(y, x): {}", result), // Expected: π/4 (approx 0.785)
    Err(e) => println!("Error: {:?}", e),
}

// Using the infallible method (panics on error in debug)
let result = ATan2::atan2(y, &x);
println!("atan2(y, x): {}", result);

// Example of an error case (0/0)
let y_zero = 0.0;
let x_zero = 0.0;
match y_zero.try_atan2(&x_zero) {
    Ok(_) => println!("This should not happen for 0/0"),
    Err(e) => println!("Error for atan2(0,0): {:?}", e), // Expected: ZeroOverZero error
}

Required Associated Types§

Source

type Error: Error

The error type that is returned by the try_atan2 method.

Required Methods§

Source

fn try_atan2(self, denominator: &Self) -> Result<Self, Self::Error>

Computes the arctangent of self (numerator y) and denominator (x), returning a Result.

This method validates both inputs to ensure they are finite numbers (not NaN, Infinity, or subnormal) using the StrictFinitePolicy. The specific case where both self and denominator are zero is considered an error (ATan2InputErrors::ZeroOverZero). The computed result is also validated to be a finite number.

§Arguments

self: The numerator y of the atan2(y, x) operation.
denominator: A reference to the denominator x of the atan2(y, x) operation.

§Errors

Returns Err(Self::Error) if:

Either self or denominator fails validation (e.g., NaN, Infinity).
Both self and denominator are zero.
The computed result fails validation (e.g., results in NaN or Infinity, though this is less common for atan2 with valid finite inputs).

Source