Direction: Rename from_normalized to new_unchecked (#11425)

# Objective

`Direction2d::from_normalized` & `Direction3d::from_normalized` don't
emphasize that importance of the vector being normalized enough.

## Solution

Rename `from_normalized` to `new_unchecked` and add more documentation.

---

`Direction2d` and `Direction3d` were added somewhat recently in
#10466 (after 0.12), so I don't
think documenting the changelog and migration guide is necessary (Since
there is no major previous version to migrate from).

But here it is anyway in case it's needed:

## Changelog

- Renamed `Direction2d::from_normalized` and
`Direction3d::from_normalized` to `new_unchecked`.

## Migration Guide

- Renamed `Direction2d::from_normalized` and
`Direction3d::from_normalized` to `new_unchecked`.

---------

Co-authored-by: Tristan Guichaoua <[email protected]>
Co-authored-by: Joona Aalto <[email protected]>

Author: 3 people

crates/bevy_math/src/bounding/bounded3d/primitive_impls.rs

@@ -150,7 +150,8 @@ impl Bounded3d for Capsule {
     fn aabb_3d(&self, translation: Vec3, rotation: Quat) -> Aabb3d {
         // Get the line segment between the hemispheres of the rotated capsule
         let segment = Segment3d {
-            direction: Direction3d::from_normalized(rotation * Vec3::Y),
+            // Multiplying a normalized vector (Vec3::Y) with a rotation returns a normalized vector.
+            direction: Direction3d::new_unchecked(rotation * Vec3::Y),
             half_length: self.half_length,
         };
         let (a, b) = (segment.point1(), segment.point2());

crates/bevy_math/src/primitives/dim2.rs

@@ -24,6 +24,17 @@ impl Direction2d {
         Self::new_and_length(value).map(|(dir, _)| dir)
     }
 
+    /// Create a [`Direction2d`] from a [`Vec2`] that is already normalized.
+    ///
+    /// # Warning
+    ///
+    /// `value` must be normalized, i.e it's length must be `1.0`.
+    pub fn new_unchecked(value: Vec2) -> Self {
+        debug_assert!(value.is_normalized());
+
+        Self(value)
+    }
+
     /// Create a direction from a finite, nonzero [`Vec2`], also returning its original length.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
@@ -34,7 +45,7 @@ impl Direction2d {
 
         direction
             .map(|dir| (Self(dir), length))
-            .map_or(Err(InvalidDirectionError::from_length(length)), Ok)
+            .ok_or(InvalidDirectionError::from_length(length))
     }
 
     /// Create a direction from its `x` and `y` components.
@@ -44,12 +55,6 @@ impl Direction2d {
     pub fn from_xy(x: f32, y: f32) -> Result<Self, InvalidDirectionError> {
         Self::new(Vec2::new(x, y))
     }
-
-    /// Create a direction from a [`Vec2`] that is already normalized.
-    pub fn from_normalized(value: Vec2) -> Self {
-        debug_assert!(value.is_normalized());
-        Self(value)
-    }
 }
 
 impl TryFrom<Vec2> for Direction2d {
@@ -187,8 +192,10 @@ impl Segment2d {
     pub fn from_points(point1: Vec2, point2: Vec2) -> (Self, Vec2) {
         let diff = point2 - point1;
         let length = diff.length();
+
         (
-            Self::new(Direction2d::from_normalized(diff / length), length),
+            // We are dividing by the length here, so the vector is normalized.
+            Self::new(Direction2d::new_unchecked(diff / length), length),
             (point1 + point2) / 2.,
         )
     }
@@ -477,7 +484,7 @@ mod tests {
         );
         assert_eq!(
             Direction2d::new_and_length(Vec2::X * 6.5),
-            Ok((Direction2d::from_normalized(Vec2::X), 6.5))
+            Ok((Direction2d::X, 6.5))
         );
     }
 

crates/bevy_math/src/primitives/dim3.rs

@@ -28,6 +28,17 @@ impl Direction3d {
         Self::new_and_length(value).map(|(dir, _)| dir)
     }
 
+    /// Create a [`Direction3d`] from a [`Vec3`] that is already normalized.
+    ///
+    /// # Warning
+    ///
+    /// `value` must be normalized, i.e it's length must be `1.0`.
+    pub fn new_unchecked(value: Vec3) -> Self {
+        debug_assert!(value.is_normalized());
+
+        Self(value)
+    }
+
     /// Create a direction from a finite, nonzero [`Vec3`], also returning its original length.
     ///
     /// Returns [`Err(InvalidDirectionError)`](InvalidDirectionError) if the length
@@ -38,7 +49,7 @@ impl Direction3d {
 
         direction
             .map(|dir| (Self(dir), length))
-            .map_or(Err(InvalidDirectionError::from_length(length)), Ok)
+            .ok_or(InvalidDirectionError::from_length(length))
     }
 
     /// Create a direction from its `x`, `y`, and `z` components.
@@ -48,12 +59,6 @@ impl Direction3d {
     pub fn from_xyz(x: f32, y: f32, z: f32) -> Result<Self, InvalidDirectionError> {
         Self::new(Vec3::new(x, y, z))
     }
-
-    /// Create a direction from a [`Vec3`] that is already normalized.
-    pub fn from_normalized(value: Vec3) -> Self {
-        debug_assert!(value.is_normalized());
-        Self(value)
-    }
 }
 
 impl TryFrom<Vec3> for Direction3d {
@@ -146,8 +151,10 @@ impl Segment3d {
     pub fn from_points(point1: Vec3, point2: Vec3) -> (Self, Vec3) {
         let diff = point2 - point1;
         let length = diff.length();
+
         (
-            Self::new(Direction3d::from_normalized(diff / length), length),
+            // We are dividing by the length here, so the vector is normalized.
+            Self::new(Direction3d::new_unchecked(diff / length), length),
             (point1 + point2) / 2.,
         )
     }
@@ -423,7 +430,7 @@ mod test {
         );
         assert_eq!(
             Direction3d::new_and_length(Vec3::X * 6.5),
-            Ok((Direction3d::from_normalized(Vec3::X), 6.5))
+            Ok((Direction3d::X, 6.5))
         );
     }
 }