Merge pull request #311 from bjz/rename-vector-length

Rename Vector::length to Vector::magnitude

CHANGELOG.md

@@ -20,6 +20,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
   `Quaternion` and `Angle` to make them easier to derive, and have clearer
   formatting.
 - Marks vectors, points, matrices, and angles as `#[repr(C, packed)]`.
+- Renames the `Vector::{length, length2}` functions to `Vector::{magnitude, magnitude2}`.
 
 ### Removed
 

benches/vec.rs

@@ -54,9 +54,9 @@ bench_binop!(_bench_vector4_dot, Vector4<f32>, Vector4<f32>, dot);
 
 bench_binop!(_bench_vector3_cross, Vector3<f32>, Vector3<f32>, cross);
 
-bench_unop!(_bench_vector2_norm, Vector2<f32>, length);
+bench_unop!(_bench_vector2_magnitude, Vector2<f32>, magnitude);
-bench_unop!(_bench_vector3_norm, Vector3<f32>, length);
+bench_unop!(_bench_vector3_magnitude, Vector3<f32>, magnitude);
-bench_unop!(_bench_vector4_norm, Vector4<f32>, length);
+bench_unop!(_bench_vector4_magnitude, Vector4<f32>, magnitude);
 
 bench_unop!(_bench_vector2_normalize, Vector2<f32>, normalize);
 bench_unop!(_bench_vector3_normalize, Vector3<f32>, normalize);

src/quaternion.rs

@@ -83,7 +83,7 @@ impl<S: BaseFloat> Quaternion<S> {
     /// calculated.
     #[inline]
     pub fn magnitude2(self) -> S {
-        self.s * self.s + self.v.length2()
+        self.s * self.s + self.v.magnitude2()
     }
 
     /// The magnitude of the quaternion

src/vector.rs

@@ -127,7 +127,7 @@ pub trait Vector: Copy + Clone where
 }
 
 /// Dot product of two vectors.
-#[inline] pub fn dot<V: Vector>(a: V, b: V) -> V::Scalar { a.dot(b) }
+#[inline] pub fn dot<V: Vector>(a: V, b: V) -> V::Scalar { V::dot(a, b) }
 
 /// A 2-dimensional vector.
 ///
@@ -471,44 +471,47 @@ pub trait EuclideanVector: Vector + Sized where
     /// Returns `true` if the vector is perpendicular (at right angles) to the
     /// other vector.
     fn is_perpendicular(self, other: Self) -> bool {
-        self.dot(other).approx_eq(&Self::Scalar::zero())
+        Self::dot(self, other).approx_eq(&Self::Scalar::zero())
     }
 
-    /// Returns the squared length of the vector. This does not perform an
+    /// Returns the squared magnitude of the vector.
-    /// expensive square root operation like in the `length` method and can
+    ///
-    /// therefore be more efficient for comparing the lengths of two vectors.
+    /// This does not perform an expensive square root operation like in
+    /// `Vector::magnitude` method, and so can be used to compare vectors more
+    /// efficiently.
     #[inline]
-    fn length2(self) -> Self::Scalar {
+    fn magnitude2(self) -> Self::Scalar {
-        self.dot(self)
+        Self::dot(self, self)
     }
 
-    /// The norm of the vector.
+    /// The distance from the tail to the tip of the vector.
     #[inline]
-    fn length(self) -> Self::Scalar {
+    fn magnitude(self) -> Self::Scalar {
-        // FIXME: Not sure why this annotation is needed
+        use rust_num::Float;
-        <<Self as Vector>::Scalar as ::rust_num::Float>::sqrt(self.dot(self))
+
+        // FIXME: Not sure why we can't use method syntax for `sqrt` here...
+        Float::sqrt(self.magnitude2())
     }
 
     /// The angle between the vector and `other`, in radians.
     fn angle(self, other: Self) -> Rad<Self::Scalar>;
 
-    /// Returns a vector with the same direction, but with a `length` (or
+    /// Returns a vector with the same direction, but with a magnitude of `1`.
-    /// `norm`) of `1`.
     #[inline]
     #[must_use]
     fn normalize(self) -> Self {
         self.normalize_to(Self::Scalar::one())
     }
 
-    /// Returns a vector with the same direction and a given `length`.
+    /// Returns a vector with the same direction and a given magnitude.
     #[inline]
     #[must_use]
-    fn normalize_to(self, length: Self::Scalar) -> Self {
+    fn normalize_to(self, magnitude: Self::Scalar) -> Self {
-        self * (length / self.length())
+        self * (magnitude / self.magnitude())
     }
 
-    /// Returns the result of linarly interpolating the length of the vector
+    /// Returns the result of linearly interpolating the magnitude of the vector
-    /// towards the length of `other` by the specified amount.
+    /// towards the magnitude of `other` by the specified amount.
     #[inline]
     #[must_use]
     fn lerp(self, other: Self, amount: Self::Scalar) -> Self {
@@ -519,21 +522,21 @@ pub trait EuclideanVector: Vector + Sized where
 impl<S: BaseFloat> EuclideanVector for Vector2<S> {
     #[inline]
     fn angle(self, other: Vector2<S>) -> Rad<S> {
-        Rad::atan2(self.perp_dot(other), self.dot(other))
+        Rad::atan2(Self::perp_dot(self, other), Self::dot(self, other))
     }
 }
 
 impl<S: BaseFloat> EuclideanVector for Vector3<S> {
     #[inline]
     fn angle(self, other: Vector3<S>) -> Rad<S> {
-        Rad::atan2(self.cross(other).length(), self.dot(other))
+        Rad::atan2(self.cross(other).magnitude(), Self::dot(self, other))
     }
 }
 
 impl<S: BaseFloat> EuclideanVector for Vector4<S> {
     #[inline]
     fn angle(self, other: Vector4<S>) -> Rad<S> {
-        Rad::acos(self.dot(other) / (self.length() * other.length()))
+        Rad::acos(Self::dot(self, other) / (self.magnitude() * other.magnitude()))
     }
 }
 

tests/vector.rs

@@ -187,7 +187,7 @@ fn test_is_perpendicular() {
 }
 
 #[cfg(test)]
-mod test_length {
+mod test_magnitude {
     use cgmath::*;
 
     #[test]
@@ -195,11 +195,11 @@ mod test_length {
         let (a, a_res) = (Vector2::new(3.0f64, 4.0f64), 5.0f64); // (3, 4, 5) Pythagorean triple
         let (b, b_res) = (Vector2::new(5.0f64, 12.0f64), 13.0f64); // (5, 12, 13) Pythagorean triple
 
-        assert_eq!(a.length2(), a_res * a_res);
+        assert_eq!(a.magnitude2(), a_res * a_res);
-        assert_eq!(b.length2(), b_res * b_res);
+        assert_eq!(b.magnitude2(), b_res * b_res);
 
-        assert_eq!(a.length(), a_res);
+        assert_eq!(a.magnitude(), a_res);
-        assert_eq!(b.length(), b_res);
+        assert_eq!(b.magnitude(), b_res);
     }
 
     #[test]
@@ -207,11 +207,11 @@ mod test_length {
         let (a, a_res) = (Vector3::new(2.0f64, 3.0f64, 6.0f64), 7.0f64); // (2, 3, 6, 7) Pythagorean quadruple
         let (b, b_res) = (Vector3::new(1.0f64, 4.0f64, 8.0f64), 9.0f64); // (1, 4, 8, 9) Pythagorean quadruple
 
-        assert_eq!(a.length2(), a_res * a_res);
+        assert_eq!(a.magnitude2(), a_res * a_res);
-        assert_eq!(b.length2(), b_res * b_res);
+        assert_eq!(b.magnitude2(), b_res * b_res);
 
-        assert_eq!(a.length(), a_res);
+        assert_eq!(a.magnitude(), a_res);
-        assert_eq!(b.length(), b_res);
+        assert_eq!(b.magnitude(), b_res);
     }
 
     #[test]
@@ -219,11 +219,11 @@ mod test_length {
         let (a, a_res) = (Vector4::new(1.0f64, 2.0f64, 4.0f64, 10.0f64), 11.0f64); // (1, 2, 4, 10, 11) Pythagorean quintuple
         let (b, b_res) = (Vector4::new(1.0f64, 2.0f64, 8.0f64, 10.0f64), 13.0f64); // (1, 2, 8, 10, 13) Pythagorean quintuple
 
-        assert_eq!(a.length2(), a_res * a_res);
+        assert_eq!(a.magnitude2(), a_res * a_res);
-        assert_eq!(b.length2(), b_res * b_res);
+        assert_eq!(b.magnitude2(), b_res * b_res);
 
-        assert_eq!(a.length(), a_res);
+        assert_eq!(a.magnitude(), a_res);
-        assert_eq!(b.length(), b_res);
+        assert_eq!(b.magnitude(), b_res);
     }
 }