From 5a23b498c826a42714a383af2bca861a5553d0e1 Mon Sep 17 00:00:00 2001 From: Shane Whitmire Date: Thu, 4 Aug 2022 09:27:37 -0500 Subject: [PATCH 1/2] Added usage documentation for vector2.rs --- src/system/vector2.rs | 219 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) diff --git a/src/system/vector2.rs b/src/system/vector2.rs index d6be0cf4..b0c470ac 100644 --- a/src/system/vector2.rs +++ b/src/system/vector2.rs @@ -61,10 +61,27 @@ pub type Vector2f = Vector2; impl Vector2 { /// Creates a new vector from its coordinates. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2; + /// let v: Vector2 = Vector2::new(6969, 6969); + /// ``` pub const fn new(x: T, y: T) -> Self { Self { x, y } } /// Lossless conversion into `Vector2`. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2; + /// let vu: Vector2 = Vector2::new(6969, 6969); + /// let vi: Vector2 = vu.into_other(); + /// assert_eq!(vu.x, vi.x.try_into().unwrap()); + /// assert_eq!(vu.y, vu.y.try_into().unwrap()); + /// ``` pub fn into_other(self) -> Vector2 where T: Into, @@ -75,6 +92,22 @@ impl Vector2 { } } /// Fallible conversion into `Vector2` + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2; + /// // Passing case + /// let vi: Vector2 = Vector2::new(21, 21); + /// let vu: Vector2 = vi.try_into_other().unwrap(); // or any other Result resolution + /// assert_eq!(u32::try_from(vi.x).unwrap(), vu.x); + /// assert_eq!(u32::try_from(vi.y).unwrap(), vu.y); + /// + /// // Failing case + /// let vi: Vector2 = Vector2::new(-21, -21); + /// let vu = vi.try_into_other::(); + /// assert!(vu.is_err()); + /// ``` pub fn try_into_other(self) -> Result, T::Error> where T: TryInto, @@ -85,6 +118,16 @@ impl Vector2 { }) } /// Lossy conversion into `Vector2` + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2; + /// let vf: Vector2 = Vector2::new(696969.6969, 6969.6969); + /// let vi: Vector2 = vf.as_other(); + /// assert_eq!(vf.x as i32, vi.x); + /// assert_eq!(vf.y as i32, vi.y); + /// ``` pub fn as_other(self) -> Vector2 where T: AsPrimitive, @@ -98,10 +141,27 @@ impl Vector2 { impl + Add + Copy> Vector2 { /// Dot product of two 2D vectors. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(16, 64); + /// let b = Vector2i::new(2, 4); + /// assert_eq!(a.dot(b), 288); + /// ``` pub fn dot(self, rhs: Self) -> T { self.x * rhs.x + self.y * rhs.y } /// Square of vector's length. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(10, 9); + /// assert_eq!(a.length_sq(), 181); + /// ``` pub fn length_sq(self) -> T { self.dot(self) } @@ -109,6 +169,15 @@ impl + Add + Copy> Vector2 { impl + Sub + Copy> Vector2 { /// Z component of the cross product of two 2D vectors. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(69, 420); + /// let b = Vector2i::new(21, 101); + /// assert_eq!(a.cross(b), -1851); + /// ``` pub fn cross(self, rhs: Self) -> T { self.x * rhs.y - self.y * rhs.x } @@ -116,6 +185,15 @@ impl + Sub + Copy> Vector2 { impl> Vector2 { /// Component-wise multiplication of self and rhs. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(1, 1); + /// let b = Vector2i::new(2, 2); + /// assert_eq!(a.cwise_mul(b), Vector2i::new(2, 2)); + /// ``` pub fn cwise_mul(self, rhs: Self) -> Vector2 { Self { x: self.x * rhs.x, @@ -126,6 +204,15 @@ impl> Vector2 { impl> Vector2 { /// Component-wise division of self and rhs. Panics on divide by zero + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(69, 69); + /// let b = Vector2i::new(3, 3); + /// assert_eq!(a.cwise_div(b), Vector2i::new(23, 23)); + /// ``` pub fn cwise_div(self, rhs: Self) -> Vector2 { Vector2 { x: self.x / rhs.x, @@ -136,6 +223,20 @@ impl> Vector2 { impl + CheckedDiv> Vector2 { /// Component-wise checked division of self and rhs. Returns None on divide by zero + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// // Passing case + /// let a = Vector2i::new(69, 69); + /// let b = Vector2i::new(3, 3); + /// assert_eq!(a.cwise_checked_div(b), Some(Vector2i::new(23, 23))); + /// + /// // Failing case + /// let b = Vector2i::new(0, 3); + /// assert_eq!(a.cwise_checked_div(b), None); + /// ``` pub fn cwise_checked_div(self, rhs: Self) -> Option> { let x = self.x.checked_div(&rhs.x)?; let y = self.y.checked_div(&rhs.y)?; @@ -145,6 +246,14 @@ impl + CheckedDiv> Vector2 { impl> Vector2 { /// Returns a perpendicular vector rotated +90 degrees + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(21, -21); + /// assert_eq!(a.perpendicular(), Vector2i::new(21, 21)); + /// ``` pub fn perpendicular(self) -> Vector2 { Vector2::new(-self.y, self.x) } @@ -152,6 +261,15 @@ impl> Vector2 { impl From<(T, T)> for Vector2 { /// Constructs a `Vector2` from `(x, y)`. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector2; + /// let a: Vector2 = Vector2::from((69u16, 420u16)); + /// assert_eq!(a.x, 69u16); + /// assert_eq!(a.y, 420u16); + /// ``` fn from(src: (T, T)) -> Self { Self { x: src.0, y: src.1 } } @@ -160,6 +278,16 @@ impl From<(T, T)> for Vector2 { impl Add> for Vector2 { type Output = Vector2; + /// Performs component wise addition + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(9, 10); + /// let b = Vector2i::new(10, 9); + /// assert_ne!(a + b, Vector2i::new(21, 21)); + /// ``` fn add(self, rhs: Vector2) -> Vector2 { Vector2 { x: self.x + rhs.x, @@ -169,6 +297,17 @@ impl Add> for Vector2 { } impl AddAssign for Vector2 { + /// Performs component wise addition assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let mut a = Vector2i::new(9, 10); + /// let b = Vector2i::new(10, 9); + /// a += b; + /// assert_eq!(a, Vector2i::new(19, 19)); + /// ``` fn add_assign(&mut self, rhs: Self) { self.x += rhs.x; self.y += rhs.y; @@ -178,6 +317,16 @@ impl AddAssign for Vector2 { impl Sub> for Vector2 { type Output = Vector2; + /// Performs component wise subtraction + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(9, 10); + /// let b = Vector2i::new(10, 9); + /// assert_eq!(a - b, Vector2i::new(-1, 1)); + /// ``` fn sub(self, rhs: Vector2) -> Vector2 { Vector2 { x: self.x - rhs.x, @@ -187,6 +336,17 @@ impl Sub> for Vector2 { } impl SubAssign for Vector2 { + /// Performs component wise subtraction assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let mut a = Vector2i::new(9, 10); + /// let b = Vector2i::new(10, 9); + /// a -= b; + /// assert_eq!(a, Vector2i::new(-1, 1)); + /// ``` fn sub_assign(&mut self, rhs: Self) { self.x -= rhs.x; self.y -= rhs.y; @@ -196,6 +356,15 @@ impl SubAssign for Vector2 { impl Mul for Vector2 { type Output = Vector2; + /// Performs scalar multiplication + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(9, 10); + /// assert_eq!(a * 420, Vector2i::new(3780, 4200)); + /// ``` fn mul(self, rhs: T) -> Vector2 { Vector2 { x: self.x * rhs, @@ -205,6 +374,16 @@ impl Mul for Vector2 { } impl MulAssign for Vector2 { + /// Performs scalar multiplication assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let mut a = Vector2i::new(9, 10); + /// a *= 420; + /// assert_eq!(a, Vector2i::new(3780, 4200)); + /// ``` fn mul_assign(&mut self, rhs: T) { self.x *= rhs; self.y *= rhs; @@ -214,6 +393,15 @@ impl MulAssign for Vector2 { impl Div for Vector2 { type Output = Vector2; + /// Performs scalar division + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let a = Vector2i::new(9, 10); + /// assert_eq!(a / 3, Vector2i::new(3, 3)); + /// ``` fn div(self, rhs: T) -> Vector2 { Vector2 { x: self.x / rhs, @@ -223,6 +411,16 @@ impl Div for Vector2 { } impl DivAssign for Vector2 { + /// Performs scalar division assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// let mut a = Vector2i::new(9, 10); + /// a /= 3; + /// assert_eq!(a, Vector2i::new(3, 3)); + /// ``` fn div_assign(&mut self, rhs: T) { self.x /= rhs; self.y /= rhs; @@ -231,6 +429,18 @@ impl DivAssign for Vector2 { impl Vector2 { /// `checked_div` for scalar division + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// // Passing case + /// let a = Vector2i::new(420, 69); + /// assert_eq!(a.checked_div(1000), Some(Vector2i::new(0, 0))); + /// + /// // Failing case + /// assert_eq!(a.checked_div(0), None); + /// ``` pub fn checked_div(self, rhs: T) -> Option> { let x = self.x.checked_div(&rhs)?; let y = self.y.checked_div(&rhs)?; @@ -240,6 +450,15 @@ impl Vector2 { impl> Neg for Vector2 { type Output = Self; + /// Negates the vector + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector2i; + /// use std::ops::Neg; + /// let a = Vector2i::new(21, 21); + /// assert_eq!(a.neg(), Vector2i::new(-21, -21)); fn neg(self) -> Self { Vector2 { x: -self.x, From 6b7af6f93c804f51bb647a89aea957bea2d5ccee Mon Sep 17 00:00:00 2001 From: Shane Whitmire Date: Thu, 4 Aug 2022 10:18:19 -0500 Subject: [PATCH 2/2] Bug fixes and documentation for vector3.rs For some reason AddAssign and SubAssign for vector3 were doing the wrong thing and only adding / subtracting into the x component of the vector. --- src/system/vector3.rs | 216 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 212 insertions(+), 4 deletions(-) diff --git a/src/system/vector3.rs b/src/system/vector3.rs index 2ca9d2ef..00188690 100644 --- a/src/system/vector3.rs +++ b/src/system/vector3.rs @@ -58,10 +58,28 @@ pub struct Vector3 { impl Vector3 { /// Create a new `Vector3` with the given values. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector3; + /// let v: Vector3 = Vector3::new(1, 2, 3); + /// ``` pub const fn new(x: T, y: T, z: T) -> Self { Self { x, y, z } } /// Lossless conversion into `Vector3`. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector3; + /// let vu: Vector3 = Vector3::new(1, 2, 3); + /// let vi: Vector3 = vu.into_other(); + /// assert_eq!(i32::from(vu.x), vi.x); + /// assert_eq!(i32::from(vu.y), vi.y); + /// assert_eq!(i32::from(vu.z), vi.z); + /// ``` pub fn into_other(self) -> Vector3 where T: Into, @@ -73,6 +91,21 @@ impl Vector3 { } } /// Fallible conversion into `Vector3` + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector3; + /// let vi: Vector3 = Vector3::new(1, 2, 3); + /// let vu: Vector3 = vi.try_into_other().unwrap(); // or any other Result resolution + /// assert_eq!(u32::try_from(vi.x).unwrap(), vu.x); + /// assert_eq!(u32::try_from(vi.y).unwrap(), vu.y); + /// assert_eq!(u32::try_from(vi.z).unwrap(), vu.z); + /// + /// let vi: Vector3 = Vector3::new(-1, -2, -3); + /// let vu = vi.try_into_other::(); + /// assert!(vu.is_err()); + /// ``` pub fn try_into_other(self) -> Result, T::Error> where T: TryInto, @@ -84,6 +117,15 @@ impl Vector3 { }) } /// Lossy conversion into `Vector3` + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector3; + /// let vf: Vector3 = Vector3::new(1., 2.5, 3.3); + /// let vi: Vector3 = vf.as_other(); + /// assert_eq!(vi, Vector3::new(1, 2, 3)); + /// ``` pub fn as_other(self) -> Vector3 where T: AsPrimitive, @@ -103,10 +145,28 @@ pub type Vector3i = Vector3; impl + Add + Copy> Vector3 { /// Dot product of two 3D vectors. + /// + /// # Usage example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(9, 10, 21); + /// let b = Vector3i::new(69, 420, 101); + /// + /// assert_eq!(a.dot(b), 6942); + /// ``` pub fn dot(self, rhs: Self) -> T { self.x * rhs.x + self.y * rhs.y + self.z * rhs.z } /// Square of vector's length. + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(9, 10, 21); + /// assert_eq!(a.length_sq(), 622); + /// ``` pub fn length_sq(self) -> T { self.dot(self) } @@ -114,6 +174,15 @@ impl + Add + Copy> Vector3 { impl + Sub + Copy> Vector3 { /// Cross product of two 3D vectors. + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(9, 10, 21); + /// let b = Vector3i::new(69, 420, 101); + /// assert_eq!(a.cross(b), Vector3i::new(-7810, 540, 3090)); + /// ``` pub fn cross(self, rhs: Self) -> Vector3 { Vector3 { x: self.y * rhs.z - self.z * rhs.y, @@ -125,6 +194,15 @@ impl + Sub + Copy> Vector3 { impl> Vector3 { /// Component-wise multiplication of self and rhs. + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(1, 1, 1); + /// let b = Vector3i::new(2, 2, 2); + /// assert_eq!(a.cwise_mul(b), Vector3i::new(2, 2, 2)); + /// ``` pub fn cwise_mul(self, rhs: Self) -> Vector3 { Self { x: self.x * rhs.x, @@ -136,6 +214,15 @@ impl> Vector3 { impl> Vector3 { /// Component-wise division of self and rhs. Panics on divide by zero + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(10, 10, 10); + /// let b = Vector3i::new(3, 3, 3); + /// assert_eq!(a.cwise_div(b), Vector3i::new(3, 3, 3)); + /// ``` pub fn cwise_div(self, rhs: Self) -> Vector3 { Vector3 { x: self.x / rhs.x, @@ -147,6 +234,19 @@ impl> Vector3 { impl + CheckedDiv> Vector3 { /// Component-wise checked division of self and rhs. Returns None on divide by zero + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(10, 10, 10); + /// let b = Vector3i::new(3, 3, 3); + /// assert_eq!(a.cwise_checked_div(b), Some(Vector3i::new(3, 3, 3))); + /// + /// let a = Vector3i::new(10, 10, 10); + /// let b = Vector3i::new(3, 0, 3); + /// assert_eq!(a.cwise_checked_div(b), None); + /// ``` pub fn cwise_checked_div(self, rhs: Self) -> Option> { let x = self.x.checked_div(&rhs.x)?; let y = self.y.checked_div(&rhs.y)?; @@ -158,6 +258,16 @@ impl + CheckedDiv> Vector3 { impl Add for Vector3 { type Output = Vector3; + /// Component-wise addition + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(10, 10, 10); + /// let b = Vector3i::new(10, 10, 10); + /// assert_eq!(a + b, Vector3i::new(20, 20, 20)); + /// ``` fn add(self, rhs: Vector3) -> Vector3 { Vector3 { x: self.x + rhs.x, @@ -168,16 +278,36 @@ impl Add for Vector3 { } impl AddAssign for Vector3 { + /// Component-wise addition assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let mut a = Vector3i::new(10, 10, 10); + /// a += Vector3i::new(10, 10, 10); + /// assert_eq!(a, Vector3i::new(20, 20, 20)); + /// ``` fn add_assign(&mut self, rhs: Self) { self.x += rhs.x; - self.x += rhs.y; - self.x += rhs.z; + self.y += rhs.y; + self.z += rhs.z; } } impl Sub for Vector3 { type Output = Vector3; + /// Component-wise subtraction + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(10, 10, 10); + /// let b = Vector3i::new(10, 10, 10); + /// assert_eq!(a - b, Vector3i::new(0, 0, 0)); + /// ``` fn sub(self, rhs: Vector3) -> Vector3 { Vector3 { x: self.x - rhs.x, @@ -188,16 +318,35 @@ impl Sub for Vector3 { } impl SubAssign for Vector3 { + /// Component-wise subtraction assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let mut a = Vector3i::new(10, 10, 10); + /// a -= Vector3i::new(10, 10, 10); + /// assert_eq!(a, Vector3i::new(0, 0, 0)); + /// ``` fn sub_assign(&mut self, rhs: Self) { self.x -= rhs.x; - self.x -= rhs.y; - self.x -= rhs.z; + self.y -= rhs.y; + self.z -= rhs.z; } } impl Mul for Vector3 { type Output = Vector3; + /// scalar multiplication + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(69, 21, 19); + /// assert_eq!(a * 10, Vector3i::new(690, 210, 190)); + /// ``` fn mul(self, rhs: T) -> Vector3 { Vector3 { x: self.x * rhs, @@ -208,6 +357,16 @@ impl Mul for Vector3 { } impl MulAssign for Vector3 { + /// scalar multiplication assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let mut a = Vector3i::new(69, 21, 19); + /// a *= 10; + /// assert_eq!(a, Vector3i::new(690, 210, 190)); + /// ``` fn mul_assign(&mut self, rhs: T) { self.x *= rhs; self.y *= rhs; @@ -218,6 +377,15 @@ impl MulAssign for Vector3 { impl Div for Vector3 { type Output = Vector3; + /// Scalar division + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::new(10, 10, 10); + /// assert_eq!(a / 3, Vector3i::new(3, 3, 3)); + /// ``` fn div(self, rhs: T) -> Vector3 { Vector3 { x: self.x / rhs, @@ -228,6 +396,16 @@ impl Div for Vector3 { } impl DivAssign for Vector3 { + /// Scalar division assignment + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let mut a = Vector3i::new(10, 10, 10); + /// a /= 3; + /// assert_eq!(a, Vector3i::new(3, 3, 3)); + /// ``` fn div_assign(&mut self, rhs: T) { self.x /= rhs; self.y /= rhs; @@ -237,6 +415,18 @@ impl DivAssign for Vector3 { impl Vector3 { /// `checked_div` for scalar division + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// // Passing case + /// let a = Vector3i::new(10, 10, 10); + /// assert_eq!(a.checked_div(3), Some(Vector3i::new(3, 3, 3))); + /// + /// // Failing case + /// assert_eq!(a.checked_div(0), None); + /// ``` pub fn checked_div(self, rhs: T) -> Option> { let x = self.x.checked_div(&rhs)?; let y = self.y.checked_div(&rhs)?; @@ -248,6 +438,16 @@ impl Vector3 { impl> Neg for Vector3 { type Output = Self; + /// Negates the vector + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// use std::ops::Neg; + /// let a = Vector3i::new(-69, 21, -10); + /// assert_eq!(a.neg(), Vector3i::new(69, -21, 10)); + /// ``` fn neg(self) -> Self { Vector3 { x: -self.x, @@ -259,6 +459,14 @@ impl> Neg for Vector3 { impl From<(T, T, T)> for Vector3 { /// Constructs a `Vector3` from `(x, y, z)`. + /// + /// # Usage Example + /// + /// ``` + /// # use sfml::system::Vector3i; + /// let a = Vector3i::from((1, 2, 3)); + /// assert_eq!(a, Vector3i::new(1, 2, 3)); + /// ``` fn from(src: (T, T, T)) -> Self { Self { x: src.0,