From e410e69e2f28b4e5f9ef276247d5dea134107fa9 Mon Sep 17 00:00:00 2001 From: Jason Travis Smith Date: Sun, 4 Oct 2015 23:33:37 -0400 Subject: [PATCH] Fixed up some tests and wrote some documentation. Also, .swp files are now ignored. --- .gitignore | 1 + src/lib.rs | 3 ++ src/vector.rs | 115 ++++++++++++++++++++++++++++++++++++++++++++++++ tests/vector.rs | 5 +-- 4 files changed, 121 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index a9d37c5..d4f917d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ target Cargo.lock +*.swp diff --git a/src/lib.rs b/src/lib.rs index 789eecc..909cc3d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,3 +11,6 @@ pub mod vector; pub use self::vector::Vector; +pub use self::vector::Vector2; +pub use self::vector::Vector3; +pub use self::vector::Vector4; diff --git a/src/vector.rs b/src/vector.rs index 58cf4c1..b81c6a2 100644 --- a/src/vector.rs +++ b/src/vector.rs @@ -10,15 +10,52 @@ pub trait Vector : Clone where T: Number { // Creation functions. /// Create a Vector from a single value. + /// + ///``` + /// // Create a new Vector3 where all + /// // the components are 3.4. + /// use sigils::vector::*; + /// + /// let vector = Vector3::::from_value(3.4f32); + /// # assert_eq!(vector.x, 3.4f32); + /// # assert_eq!(vector.y, 3.4f32); + /// # assert_eq!(vector.z, 3.4f32); + ///``` fn from_value(val: T) -> Self; /// Create a zero Vector. All components will be set to zero. + /// + /// ``` + /// // Create a new Vector4 where all + /// // the components are 0. + /// use sigils::vector::*; + /// + /// let vector = Vector4::::zero(); + /// # assert_eq!(vector.x, 0u8); + /// # assert_eq!(vector.y, 0u8); + /// # assert_eq!(vector.z, 0u8); + /// # assert_eq!(vector.w, 0u8); + /// ``` + // TODO: Should Vectors implement the Zero trait + // instead of defining a function for it? fn zero() -> Self { Self::from_value(T::zero()) } /// Create an identity Vector. All components will be set to one. + /// + /// ``` + /// // Create a new Vector2 where all + /// // the components are 1. + /// use sigils::vector::*; + /// + /// let vector = Vector2::::identity(); + /// # assert_eq!(vector.x, 1i32); + /// # assert_eq!(vector.y, 1i32); + /// ``` + // TODO: Should Vectors implement the One trait + // instead of defining an identity function? fn identity() -> Self { Self::from_value(T::one()) @@ -27,19 +64,81 @@ pub trait Vector : Clone where T: Number // Scalar operations that result in a new Vector. /// Add a scalar value to this Vector and return a new Vector. + /// + /// ``` + /// // Create a new Vector2 where all + /// // the components are 1. Then add 1 to it. + /// use sigils::vector::*; + /// + /// let vector = Vector2::::identity(); + /// let vector_two = vector.add_scalar(1i32); + /// # assert_eq!(vector_two.x, 2i32); + /// # assert_eq!(vector_two.y, 2i32); + /// ``` fn add_scalar(&self, scalar: T) -> Self; /// Subtract a scalar value from this Vector and return a new Vector. + /// + /// ``` + /// // Create a new Vector4 where all + /// // the components are 1. Then subtract 1 from it. + /// use sigils::vector::*; + /// + /// let vector = Vector4::::identity(); + /// let vector_two = vector.sub_scalar(1.0f64); + /// # assert_eq!(vector_two.x, 0f64); + /// # assert_eq!(vector_two.y, 0f64); + /// # assert_eq!(vector_two.z, 0f64); + /// # assert_eq!(vector_two.w, 0f64); + /// ``` fn sub_scalar(&self, scalar: T) -> Self; /// Multiply this Vector by a scalar value and return a new Vector. + /// + /// ``` + /// // Create a new Vector4 where all + /// // the components are 5. Then multiply it by 5. + /// use sigils::vector::*; + /// + /// let vector = Vector4::::from_value(5f32); + /// let vector_two = vector.mul_scalar(5f32); + /// # assert_eq!(vector_two.x, 25f32); + /// # assert_eq!(vector_two.y, 25f32); + /// # assert_eq!(vector_two.z, 25f32); + /// # assert_eq!(vector_two.w, 25f32); + /// ``` fn mul_scalar(&self, scalar: T) -> Self; /// Divide this Vector by a scalar value and return a new Vector. + /// + /// ``` + /// // Create a new Vector3 where all + /// // the components are 25. Then divide it by 5. + /// use sigils::vector::*; + /// + /// let vector = Vector3::::from_value(25u8); + /// let vector_two = vector.div_scalar(5u8); + /// # assert_eq!(vector_two.x, 5u8); + /// # assert_eq!(vector_two.y, 5u8); + /// # assert_eq!(vector_two.z, 5u8); + /// ``` fn div_scalar(&self, scalar: T) -> Self; /// Divide this Vector by a scalar value, take the remainder, /// and return a new Vector. + /// + /// ``` + /// // Create a new Vector3 where all + /// // the components are 25. Then divide it by 7 + /// // and take the remainder. + /// use sigils::vector::*; + /// + /// let vector = Vector3::::from_value(25isize); + /// let vector_two = vector.rem_scalar(7isize); + /// # assert_eq!(vector_two.x, 4isize); + /// # assert_eq!(vector_two.y, 4isize); + /// # assert_eq!(vector_two.z, 4isize); + /// ``` fn rem_scalar(&self, scalar: T) -> Self; @@ -94,6 +193,7 @@ pub trait Vector : Clone where T: Number /// Divide this Vector by a Vector and take the remainder. fn rem_vector_self(&mut self, vector: &Self); + // TODO: Look at defining negation // Basic Vector functions. /// Get the sum of all the components of the Vector. @@ -168,6 +268,10 @@ macro_rules! define_vector { ($structName: ident <$T: ident> {$($field: ident),+}) => { + /// This structure was defined with the macro + /// define_vector. + /// + /// Please excuse the lack of comments. #[derive(PartialEq, Eq, Copy, Clone, Hash)] pub struct $structName where T: Number { @@ -323,11 +427,13 @@ define_vector!(Vector4 {x, y, z, w}); // Vector structure sizes. impl Vector2 where T: Number { + /// Create a unit Vector in the X direction. pub fn unit_x() -> Vector2 { Vector2::new(T::one(), T::zero()) } + /// Create a unit Vector in the Y direction. pub fn unit_y() -> Vector2 { Vector2::new(T::zero(), T::one()) @@ -341,21 +447,26 @@ impl Vector2 where T: Number impl Vector3 where T: Number { + /// Create a unit Vector in the X direction. pub fn unit_x() -> Vector3 { Vector3::new(T::one(), T::zero(), T::zero()) } + /// Create a unit Vector in the Y direction. pub fn unit_y() -> Vector3 { Vector3::new(T::zero(), T::one(), T::zero()) } + /// Create a unit Vector in the Z direction. pub fn unit_z() -> Vector3 { Vector3::new(T::zero(), T::zero(), T::one()) } + /// Calculate the cross product between this and another Vector. + /// It will return a Vector perpendicular to both of the input Vectors. pub fn cross(&self, vector: &Vector3) -> Vector3 { Vector3::new((self.y * vector.z) - (self.z * vector.y), @@ -366,21 +477,25 @@ impl Vector3 where T: Number impl Vector4 where T: Number { + /// Create a unit Vector in the X direction. pub fn unit_x() -> Vector4 { Vector4::new(T::one(), T::zero(), T::zero(), T::zero()) } + /// Create a unit Vector in the Y direction. pub fn unit_y() -> Vector4 { Vector4::new(T::zero(), T::one(), T::zero(), T::zero()) } + /// Create a unit Vector in the Z direction. pub fn unit_z() -> Vector4 { Vector4::new(T::zero(), T::zero(), T::one(), T::zero()) } + /// Create a unit Vector in the W direction. pub fn unit_w() -> Vector4 { Vector4::new(T::zero(), T::zero(), T::zero(), T::one()) diff --git a/tests/vector.rs b/tests/vector.rs index ab7ef59..9ef7487 100644 --- a/tests/vector.rs +++ b/tests/vector.rs @@ -1,13 +1,12 @@ extern crate sigils; -use sigils::Vector; +use sigils::vector::*; #[test] fn vector_creation() { - let v: Vector; + let v: Vector3 = Vector3::::from_value(1.0f32); - v = Vector::new(); assert_eq!(v.x, 1.0f32); }