ATan2

num_valid::functions

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

§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, 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 = y.atan2(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

fn atan2(self, denominator: &Self) -> Self

Computes the arctangent of self (numerator y) and denominator (x), returning the result directly.

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 ATan2 for f64

Source§

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

The error type that is returned by the try_atan2 method.

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).
§Note on Infinite Inputs

This implementation, using StrictFinitePolicy, rejects infinite inputs and returns an InvalidArgument error. This differs from some standard library implementations (like libm or std::f64::atan2) which may return specific values for infinite arguments.

Source§

fn atan2(self, denominator: &Self) -> Self

Computes the arctangent of self (numerator y) and denominator (x), returning the result directly.

§Behavior
  • In debug builds (#[cfg(debug_assertions)]): This method calls try_atan2() and unwraps the result. It will panic if try_atan2 returns an error.
  • In release builds (#[cfg(not(debug_assertions))]): This method typically calls the underlying standard library’s atan2 function directly for performance, bypassing the explicit validations performed by try_atan2.
§Arguments
  • self: The numerator y of the atan2(y, x) operation.
  • denominator: A reference to the denominator x of the atan2(y, x) operation.
§Panics

This method will panic in debug builds if try_atan2() would return an Err. In release builds, the behavior for invalid inputs (like NaN or Infinity) will match the underlying standard library function (e.g., f64::atan2(f64::NAN, 1.0) is NAN).

Implementors§