Rename Vec2::angle_between to Vec2::angle_to (#524)

This method has a different meaning to Vec3::angle_between, which was
inconsistent and confusing.

benches/vec2.rs

@@ -25,9 +25,9 @@ bench_binop!(
 );
 
 bench_binop!(
-    vec2_angle_between,
-    "vec2 angle_between",
-    op => angle_between,
+    vec2_angle_to,
+    "vec2 angle_to",
+    op => angle_to,
     from1 => random_vec2,
     from2 => random_vec2
 );
@@ -45,7 +45,7 @@ criterion_group!(
     vec2_mul_vec2,
     vec2_euler,
     vec2_select,
-    vec2_angle_between
+    vec2_angle_to
 );
 
 criterion_main!(benches);

codegen/templates/vec.rs.tera

@@ -1983,12 +1983,22 @@ impl {{ self_t }} {
         math::atan2(self.y, self.x)
     }
 
-    /// Returns the angle (in radians) between `self` and `rhs` in the range `[-π, +π]`.
+    #[inline]
+    #[must_use]
+    #[deprecated(
+        since = "0.27.0",
+        note = "Use angle_to() instead, the semantics of angle_between will change in the future."
+    )]
+    pub fn angle_between(self, rhs: Self) -> {{ scalar_t }} {
+        self.angle_to(rhs)
+    }
+
+    /// Returns the angle of rotation (in radians) from `self` to `rhs` in the range `[-π, +π]`.
     ///
     /// The inputs do not need to be unit vectors however they must be non-zero.
     #[inline]
     #[must_use]
-    pub fn angle_between(self, rhs: Self) -> {{ scalar_t }} {
+    pub fn angle_to(self, rhs: Self) -> {{ scalar_t }} {
         let angle = math::acos_approx(
             self.dot(rhs) / math::sqrt(self.length_squared() * rhs.length_squared()));
 
@@ -2107,7 +2117,7 @@ impl {{ self_t }} {
     #[inline]
     #[must_use]
     pub fn rotate_towards(&self, rhs: Self, max_angle: {{ scalar_t }}) -> Self {
-        let a = self.angle_between(rhs);
+        let a = self.angle_to(rhs);
         let abs_a = math::abs(a);
         if abs_a <= 1e-4 {
             return rhs;

src/f32/vec2.rs

@@ -806,12 +806,22 @@ impl Vec2 {
         math::atan2(self.y, self.x)
     }
 
-    /// Returns the angle (in radians) between `self` and `rhs` in the range `[-π, +π]`.
+    #[inline]
+    #[must_use]
+    #[deprecated(
+        since = "0.27.0",
+        note = "Use angle_to() instead, the semantics of angle_between will change in the future."
+    )]
+    pub fn angle_between(self, rhs: Self) -> f32 {
+        self.angle_to(rhs)
+    }
+
+    /// Returns the angle of rotation (in radians) from `self` to `rhs` in the range `[-π, +π]`.
     ///
     /// The inputs do not need to be unit vectors however they must be non-zero.
     #[inline]
     #[must_use]
-    pub fn angle_between(self, rhs: Self) -> f32 {
+    pub fn angle_to(self, rhs: Self) -> f32 {
         let angle = math::acos_approx(
             self.dot(rhs) / math::sqrt(self.length_squared() * rhs.length_squared()),
         );
@@ -860,7 +870,7 @@ impl Vec2 {
     #[inline]
     #[must_use]
     pub fn rotate_towards(&self, rhs: Self, max_angle: f32) -> Self {
-        let a = self.angle_between(rhs);
+        let a = self.angle_to(rhs);
         let abs_a = math::abs(a);
         if abs_a <= 1e-4 {
             return rhs;

src/f64/dvec2.rs

@@ -806,12 +806,22 @@ impl DVec2 {
         math::atan2(self.y, self.x)
     }
 
-    /// Returns the angle (in radians) between `self` and `rhs` in the range `[-π, +π]`.
+    #[inline]
+    #[must_use]
+    #[deprecated(
+        since = "0.27.0",
+        note = "Use angle_to() instead, the semantics of angle_between will change in the future."
+    )]
+    pub fn angle_between(self, rhs: Self) -> f64 {
+        self.angle_to(rhs)
+    }
+
+    /// Returns the angle of rotation (in radians) from `self` to `rhs` in the range `[-π, +π]`.
     ///
     /// The inputs do not need to be unit vectors however they must be non-zero.
     #[inline]
     #[must_use]
-    pub fn angle_between(self, rhs: Self) -> f64 {
+    pub fn angle_to(self, rhs: Self) -> f64 {
         let angle = math::acos_approx(
             self.dot(rhs) / math::sqrt(self.length_squared() * rhs.length_squared()),
         );
@@ -860,7 +870,7 @@ impl DVec2 {
     #[inline]
     #[must_use]
     pub fn rotate_towards(&self, rhs: Self, max_angle: f64) -> Self {
-        let a = self.angle_between(rhs);
+        let a = self.angle_to(rhs);
         let abs_a = math::abs(a);
         if abs_a <= 1e-4 {
             return rhs;

tests/vec2.rs

@@ -897,15 +897,22 @@ macro_rules! impl_vec2_float_tests {
             );
         });
 
-        glam_test!(test_angle_between, {
-            let angle = $vec2::new(1.0, 0.0).angle_between($vec2::new(0.0, 1.0));
+        glam_test!(test_angle_to, {
+            let angle = $vec2::new(1.0, 0.0).angle_to($vec2::new(0.0, 1.0));
             assert_approx_eq!(core::$t::consts::FRAC_PI_2, angle, 1e-6);
 
-            let angle = $vec2::new(10.0, 0.0).angle_between($vec2::new(0.0, 5.0));
+            let angle = $vec2::new(10.0, 0.0).angle_to($vec2::new(0.0, 5.0));
             assert_approx_eq!(core::$t::consts::FRAC_PI_2, angle, 1e-6);
 
-            let angle = $vec2::new(-1.0, 0.0).angle_between($vec2::new(0.0, 1.0));
+            let angle = $vec2::new(-1.0, 0.0).angle_to($vec2::new(0.0, 1.0));
             assert_approx_eq!(-core::$t::consts::FRAC_PI_2, angle, 1e-6);
+
+            // the angle returned by angle_to should rotate the input vector to the
+            // destination vector
+            assert_approx_eq!(
+                $vec2::from_angle($vec2::X.angle_to($vec2::Y)).rotate($vec2::X),
+                $vec2::Y
+            );
         });
 
         glam_test!(test_clamp_length, {