From ff5b64e35d3e5efa04a18dcf6888016f6173bf46 Mon Sep 17 00:00:00 2001 From: sebcrozet Date: Mon, 5 Nov 2018 10:15:49 +0100 Subject: [PATCH] Add doc-tests to unit_complex.rs. --- src/geometry/rotation.rs | 2 +- src/geometry/rotation_specialization.rs | 3 +- src/geometry/unit_complex.rs | 135 ++++++++++++++++++++++++ 3 files changed, 138 insertions(+), 2 deletions(-) diff --git a/src/geometry/rotation.rs b/src/geometry/rotation.rs index 4b328e68..f53668c7 100644 --- a/src/geometry/rotation.rs +++ b/src/geometry/rotation.rs @@ -178,7 +178,7 @@ where DefaultAllocator: Allocator /// /// # Example /// ``` - /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix2, Matrix3, Matrix4}; + /// # use nalgebra::{Rotation2, Rotation3, Vector3, Matrix3, Matrix4}; /// # use std::f32; /// let rot = Rotation3::from_axis_angle(&Vector3::z_axis(), f32::consts::FRAC_PI_6); /// let expected = Matrix4::new(0.8660254, -0.5, 0.0, 0.0, diff --git a/src/geometry/rotation_specialization.rs b/src/geometry/rotation_specialization.rs index 62227c1a..350fdd27 100644 --- a/src/geometry/rotation_specialization.rs +++ b/src/geometry/rotation_specialization.rs @@ -126,6 +126,7 @@ impl Rotation2 { /// let rot1 = Rotation2::new(0.1); /// let rot2 = Rotation2::new(1.7); /// assert_relative_eq!(rot1.angle_to(&rot2), 1.6); + /// ``` #[inline] pub fn angle_to(&self, other: &Rotation2) -> N { self.rotation_to(other).angle() @@ -160,7 +161,7 @@ impl Rotation2 { /// # use nalgebra::Rotation2; /// let rot = Rotation2::new(0.78); /// let pow = rot.powf(2.0); - /// assert_eq!(pow.angle(), 1.56); + /// assert_eq!(pow.angle(), 2.0 * 0.78); /// ``` #[inline] pub fn powf(&self, n: N) -> Rotation2 { diff --git a/src/geometry/unit_complex.rs b/src/geometry/unit_complex.rs index 63ddf80f..32bb0238 100644 --- a/src/geometry/unit_complex.rs +++ b/src/geometry/unit_complex.rs @@ -11,24 +11,50 @@ pub type UnitComplex = Unit>; impl UnitComplex { /// The rotation angle in `]-pi; pi]` of this unit complex number. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let rot = UnitComplex::new(1.78); + /// assert_eq!(rot.angle(), 1.78); + /// ``` #[inline] pub fn angle(&self) -> N { self.im.atan2(self.re) } /// The sine of the rotation angle. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let angle = 1.78f32; + /// let rot = UnitComplex::new(angle); + /// assert_eq!(rot.sin_angle(), angle.sin()); + /// ``` #[inline] pub fn sin_angle(&self) -> N { self.im } /// The cosine of the rotation angle. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let angle = 1.78f32; + /// let rot = UnitComplex::new(angle); + /// assert_eq!(rot.cos_angle(),angle.cos()); + /// ``` #[inline] pub fn cos_angle(&self) -> N { self.re } /// The rotation angle returned as a 1-dimensional vector. + /// + /// This is generally used in the context of generic programming. Using + /// the `.angle()` method instead is more common. #[inline] pub fn scaled_axis(&self) -> Vector1 { Vector1::new(self.angle()) @@ -36,6 +62,8 @@ impl UnitComplex { /// The rotation axis and angle in ]0, pi] of this complex number. /// + /// This is generally used in the context of generic programming. Using + /// the `.angle()` method instead is more common. /// Returns `None` if the angle is zero. #[inline] pub fn axis_angle(&self) -> Option<(Unit>, N)> { @@ -53,24 +81,65 @@ impl UnitComplex { /// The underlying complex number. /// /// Same as `self.as_ref()`. + /// + /// # Example + /// ``` + /// # extern crate num_complex; + /// # extern crate nalgebra; + /// # use num_complex::Complex; + /// # use nalgebra::UnitComplex; + /// let angle = 1.78f32; + /// let rot = UnitComplex::new(angle); + /// assert_eq!(*rot.complex(), Complex::new(angle.cos(), angle.sin())); + /// ``` #[inline] pub fn complex(&self) -> &Complex { self.as_ref() } /// Compute the conjugate of this unit complex number. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let rot = UnitComplex::new(1.78); + /// let conj = rot.conjugate(); + /// assert_eq!(rot.complex().im, -conj.complex().im); + /// assert_eq!(rot.complex().re, conj.complex().re); + /// ``` #[inline] pub fn conjugate(&self) -> Self { UnitComplex::new_unchecked(self.conj()) } /// Inverts this complex number if it is not zero. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::UnitComplex; + /// let rot = UnitComplex::new(1.2); + /// let inv = rot.inverse(); + /// assert_relative_eq!(rot * inv, UnitComplex::identity(), epsilon = 1.0e-6); + /// assert_relative_eq!(inv * rot, UnitComplex::identity(), epsilon = 1.0e-6); + /// ``` #[inline] pub fn inverse(&self) -> Self { self.conjugate() } /// The rotation angle needed to make `self` and `other` coincide. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::UnitComplex; + /// let rot1 = UnitComplex::new(0.1); + /// let rot2 = UnitComplex::new(1.7); + /// assert_relative_eq!(rot1.angle_to(&rot2), 1.6); + /// ``` #[inline] pub fn angle_to(&self, other: &Self) -> N { let delta = self.rotation_to(other); @@ -80,12 +149,38 @@ impl UnitComplex { /// The unit complex number needed to make `self` and `other` coincide. /// /// The result is such that: `self.rotation_to(other) * self == other`. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::UnitComplex; + /// let rot1 = UnitComplex::new(0.1); + /// let rot2 = UnitComplex::new(1.7); + /// let rot_to = rot1.rotation_to(&rot2); + /// + /// assert_relative_eq!(rot_to * rot1, rot2); + /// assert_relative_eq!(rot_to.inverse() * rot2, rot1); + /// ``` #[inline] pub fn rotation_to(&self, other: &Self) -> Self { other / self } /// Compute in-place the conjugate of this unit complex number. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::UnitComplex; + /// let angle = 1.7; + /// let rot = UnitComplex::new(angle); + /// let mut conj = UnitComplex::new(angle); + /// conj.conjugate_mut(); + /// assert_eq!(rot.complex().im, -conj.complex().im); + /// assert_eq!(rot.complex().re, conj.complex().re); + /// ``` #[inline] pub fn conjugate_mut(&mut self) { let me = self.as_mut_unchecked(); @@ -93,6 +188,18 @@ impl UnitComplex { } /// Inverts in-place this unit complex number. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::UnitComplex; + /// let angle = 1.7; + /// let mut rot = UnitComplex::new(angle); + /// rot.inverse_mut(); + /// assert_relative_eq!(rot * UnitComplex::new(angle), UnitComplex::identity()); + /// assert_relative_eq!(UnitComplex::new(angle) * rot, UnitComplex::identity()); + /// ``` #[inline] pub fn inverse_mut(&mut self) { self.conjugate_mut() @@ -102,12 +209,29 @@ impl UnitComplex { /// /// This returns the unit complex number that identifies a rotation angle equal to /// `self.angle() × n`. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let rot = UnitComplex::new(0.78); + /// let pow = rot.powf(2.0); + /// assert_eq!(pow.angle(), 2.0 * 0.78); + /// ``` #[inline] pub fn powf(&self, n: N) -> Self { Self::from_angle(self.angle() * n) } /// Builds the rotation matrix corresponding to this unit complex number. + /// + /// # Example + /// ``` + /// # use nalgebra::{UnitComplex, Rotation2}; + /// # use std::f32; + /// let rot = UnitComplex::new(f32::consts::FRAC_PI_6); + /// let expected = Rotation2::new(f32::consts::FRAC_PI_6); + /// assert_eq!(rot.to_rotation_matrix(), expected); + /// ``` #[inline] pub fn to_rotation_matrix(&self) -> Rotation2 { let r = self.re; @@ -117,6 +241,17 @@ impl UnitComplex { } /// Converts this unit complex number into its equivalent homogeneous transformation matrix. + /// + /// # Example + /// ``` + /// # use nalgebra::{UnitComplex, Matrix3}; + /// # use std::f32; + /// let rot = UnitComplex::new(f32::consts::FRAC_PI_6); + /// let expected = Matrix3::new(0.8660254, -0.5, 0.0, + /// 0.5, 0.8660254, 0.0, + /// 0.0, 0.0, 1.0); + /// assert_eq!(rot.to_homogeneous(), expected); + /// ``` #[inline] pub fn to_homogeneous(&self) -> Matrix3 { self.to_rotation_matrix().to_homogeneous()