Impl TryFrom vector for directions and add InvalidDirectionError (#…

…10884)

# Objective

Implement `TryFrom<Vec2>`/`TryFrom<Vec3>` for direction primitives as
considered in #10857.

## Solution

Implement `TryFrom` for the direction primitives.

These are all equivalent:

```rust
let dir2d = Direction2d::try_from(Vec2::new(0.5, 0.5)).unwrap();
let dir2d = Vec2::new(0.5, 0.5).try_into().unwrap(); // (assumes that the type is inferred)
let dir2d = Direction2d::new(Vec2::new(0.5, 0.5)).unwrap();
```

For error cases, an `Err(InvalidDirectionError)` is returned. It
contains the type of failure:

```rust
/// An error indicating that a direction is invalid.
#[derive(Debug, PartialEq)]
pub enum InvalidDirectionError {
    /// The length of the direction vector is zero or very close to zero.
    Zero,
    /// The length of the direction vector is `std::f32::INFINITY`.
    Infinite,
    /// The length of the direction vector is `NaN`.
    NaN,
}
```

crates/bevy_math/src/primitives/dim2.rs

@@ -1,16 +1,30 @@
-use super::{Primitive2d, WindingOrder};
+use super::{InvalidDirectionError, Primitive2d, WindingOrder};
 use crate::Vec2;
 
 /// A normalized vector pointing in a direction in 2D space
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Direction2d(Vec2);
 
 impl Direction2d {
  /// Create a direction from a finite, nonzero [`Vec2`].
  ///
- /// Returns `None` if the input is zero (or very close to zero), or non-finite.
- pub fn new(value: Vec2) -> Option<Self> {
- value.try_normalize().map(Self)
+ /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
+ /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
+ pub fn new(value: Vec2) -> Result<Self, InvalidDirectionError> {
+ value.try_normalize().map(Self).map_or_else(
+ || {
+ if value.is_nan() {
+ Err(InvalidDirectionError::NaN)
+ } else if !value.is_finite() {
+ // If the direction is non-finite but also not NaN, it must be infinite
+ Err(InvalidDirectionError::Infinite)
+ } else {
+ // If the direction is invalid but neither NaN nor infinite, it must be zero
+ Err(InvalidDirectionError::Zero)
+ }
+ },
+ Ok,
+ )
  }
 
  /// Create a direction from a [`Vec2`] that is already normalized
@@ -20,6 +34,14 @@ impl Direction2d {
  }
 }
 
+impl TryFrom<Vec2> for Direction2d {
+ type Error = InvalidDirectionError;
+
+ fn try_from(value: Vec2) -> Result<Self, Self::Error> {
+ Self::new(value)
+ }
+}
+
 impl std::ops::Deref for Direction2d {
  type Target = Vec2;
  fn deref(&self) -> &Self::Target {
@@ -324,6 +346,30 @@ impl RegularPolygon {
 mod tests {
  use super::*;
 
+ #[test]
+ fn direction_creation() {
+ assert_eq!(
+ Direction2d::new(Vec2::X * 12.5),
+ Ok(Direction2d::from_normalized(Vec2::X))
+ );
+ assert_eq!(
+ Direction2d::new(Vec2::new(0.0, 0.0)),
+ Err(InvalidDirectionError::Zero)
+ );
+ assert_eq!(
+ Direction2d::new(Vec2::new(std::f32::INFINITY, 0.0)),
+ Err(InvalidDirectionError::Infinite)
+ );
+ assert_eq!(
+ Direction2d::new(Vec2::new(std::f32::NEG_INFINITY, 0.0)),
+ Err(InvalidDirectionError::Infinite)
+ );
+ assert_eq!(
+ Direction2d::new(Vec2::new(std::f32::NAN, 0.0)),
+ Err(InvalidDirectionError::NaN)
+ );
+ }
+
  #[test]
  fn triangle_winding_order() {
  let mut cw_triangle = Triangle2d::new(

crates/bevy_math/src/primitives/dim3.rs

@@ -1,16 +1,30 @@
-use super::Primitive3d;
+use super::{InvalidDirectionError, Primitive3d};
 use crate::Vec3;
 
 /// A normalized vector pointing in a direction in 3D space
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq)]
 pub struct Direction3d(Vec3);
 
 impl Direction3d {
  /// Create a direction from a finite, nonzero [`Vec3`].
  ///
- /// Returns `None` if the input is zero (or very close to zero), or non-finite.
- pub fn new(value: Vec3) -> Option<Self> {
- value.try_normalize().map(Self)
+ /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
+ /// of the given vector is zero (or very close to zero), infinite, or `NaN`.
+ pub fn new(value: Vec3) -> Result<Self, InvalidDirectionError> {
+ value.try_normalize().map(Self).map_or_else(
+ || {
+ if value.is_nan() {
+ Err(InvalidDirectionError::NaN)
+ } else if !value.is_finite() {
+ // If the direction is non-finite but also not NaN, it must be infinite
+ Err(InvalidDirectionError::Infinite)
+ } else {
+ // If the direction is invalid but neither NaN nor infinite, it must be zero
+ Err(InvalidDirectionError::Zero)
+ }
+ },
+ Ok,
+ )
  }
 
  /// Create a direction from a [`Vec3`] that is already normalized
@@ -20,6 +34,14 @@ impl Direction3d {
  }
 }
 
+impl TryFrom<Vec3> for Direction3d {
+ type Error = InvalidDirectionError;
+
+ fn try_from(value: Vec3) -> Result<Self, Self::Error> {
+ Self::new(value)
+ }
+}
+
 impl std::ops::Deref for Direction3d {
  type Target = Vec3;
  fn deref(&self) -> &Self::Target {
@@ -332,3 +354,32 @@ impl Torus {
  }
  }
 }
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn direction_creation() {
+ assert_eq!(
+ Direction3d::new(Vec3::X * 12.5),
+ Ok(Direction3d::from_normalized(Vec3::X))
+ );
+ assert_eq!(
+ Direction3d::new(Vec3::new(0.0, 0.0, 0.0)),
+ Err(InvalidDirectionError::Zero)
+ );
+ assert_eq!(
+ Direction3d::new(Vec3::new(std::f32::INFINITY, 0.0, 0.0)),
+ Err(InvalidDirectionError::Infinite)
+ );
+ assert_eq!(
+ Direction3d::new(Vec3::new(std::f32::NEG_INFINITY, 0.0, 0.0)),
+ Err(InvalidDirectionError::Infinite)
+ );
+ assert_eq!(
+ Direction3d::new(Vec3::new(std::f32::NAN, 0.0, 0.0)),
+ Err(InvalidDirectionError::NaN)
+ );
+ }
+}

crates/bevy_math/src/primitives/mod.rs

@@ -13,6 +13,26 @@ pub trait Primitive2d {}
 /// A marker trait for 3D primitives
 pub trait Primitive3d {}
 
+/// An error indicating that a direction is invalid.
+#[derive(Debug, PartialEq)]
+pub enum InvalidDirectionError {
+ /// The length of the direction vector is zero or very close to zero.
+ Zero,
+ /// The length of the direction vector is `std::f32::INFINITY`.
+ Infinite,
+ /// The length of the direction vector is `NaN`.
+ NaN,
+}
+
+impl std::fmt::Display for InvalidDirectionError {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ write!(
+ f,
+ "Direction can not be zero (or very close to zero), or non-finite."
+ )
+ }
+}
+
 /// The winding order for a set of points
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum WindingOrder {