diff --git a/src/geometry/rotation_specialization.rs b/src/geometry/rotation_specialization.rs index 350fdd27..cdb7aed7 100644 --- a/src/geometry/rotation_specialization.rs +++ b/src/geometry/rotation_specialization.rs @@ -29,7 +29,7 @@ impl Rotation2 { /// # #[macro_use] extern crate approx; /// # extern crate nalgebra; /// # use std::f32; - /// # use nalgebra::{Rotation2, Vector2, Point2}; + /// # use nalgebra::{Rotation2, Point2}; /// let rot = Rotation2::new(f32::consts::FRAC_PI_2); /// /// assert_relative_eq!(rot * Point2::new(3.0, 4.0), Point2::new(-4.0, 3.0)); diff --git a/src/geometry/unit_complex_construction.rs b/src/geometry/unit_complex_construction.rs index 8e4f45fe..d8917e41 100644 --- a/src/geometry/unit_complex_construction.rs +++ b/src/geometry/unit_complex_construction.rs @@ -11,16 +11,38 @@ use base::allocator::Allocator; use base::dimension::{U1, U2}; use base::storage::Storage; use base::{DefaultAllocator, Unit, Vector}; -use geometry::{Rotation, UnitComplex}; +use geometry::{Rotation2, UnitComplex}; impl UnitComplex { /// The unit complex number multiplicative identity. + /// + /// # Example + /// ``` + /// # use nalgebra::UnitComplex; + /// let rot1 = UnitComplex::identity(); + /// let rot2 = UnitComplex::new(1.7); + /// + /// assert_eq!(rot1 * rot2, rot2); + /// assert_eq!(rot2 * rot1, rot2); + /// ``` #[inline] pub fn identity() -> Self { Self::new_unchecked(Complex::new(N::one(), N::zero())) } - /// Builds the unit complex number corresponding to the rotation with the angle. + /// Builds the unit complex number corresponding to the rotation with the given angle. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{UnitComplex, Point2}; + /// let rot = UnitComplex::new(f32::consts::FRAC_PI_2); + /// + /// assert_relative_eq!(rot * Point2::new(3.0, 4.0), Point2::new(-4.0, 3.0)); + /// ``` #[inline] pub fn new(angle: N) -> Self { let (sin, cos) = angle.sin_cos(); @@ -30,6 +52,19 @@ impl UnitComplex { /// Builds the unit complex number corresponding to the rotation with the angle. /// /// Same as `Self::new(angle)`. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{UnitComplex, Point2}; + /// let rot = UnitComplex::from_angle(f32::consts::FRAC_PI_2); + /// + /// assert_relative_eq!(rot * Point2::new(3.0, 4.0), Point2::new(-4.0, 3.0)); + /// ``` + // FIXME: deprecate this. #[inline] pub fn from_angle(angle: N) -> Self { Self::new(angle) @@ -37,7 +72,21 @@ impl UnitComplex { /// Builds the unit complex number from the sinus and cosinus of the rotation angle. /// - /// The input values are not checked. + /// The input values are not checked to actually be cosines and sine of the same value. + /// Is is generally preferable to use the `::new(angle)` constructor instead. + /// + /// # Example + /// + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use std::f32; + /// # use nalgebra::{UnitComplex, Vector2, Point2}; + /// let angle = f32::consts::FRAC_PI_2; + /// let rot = UnitComplex::from_cos_sin_unchecked(angle.cos(), angle.sin()); + /// + /// assert_relative_eq!(rot * Point2::new(3.0, 4.0), Point2::new(-4.0, 3.0)); + /// ``` #[inline] pub fn from_cos_sin_unchecked(cos: N, sin: N) -> Self { UnitComplex::new_unchecked(Complex::new(cos, sin)) @@ -45,9 +94,10 @@ impl UnitComplex { /// Builds a unit complex rotation from an angle in radian wrapped in a 1-dimensional vector. /// - /// Equivalent to `Self::new(axisangle[0])`. + /// This is generally used in the context of generic programming. Using + /// the `::new(angle)` method instead is more common. #[inline] - pub fn from_scaled_axis>(axisangle: Vector) -> Self { + pub fn from_scaled_axis>(axisangle: Vector) -> Self { Self::from_angle(axisangle[0]) } @@ -61,7 +111,7 @@ impl UnitComplex { /// Creates a new unit complex number from a complex number. /// - /// The input complex number will be normalized. Returns the complex number norm as well. + /// The input complex number will be normalized. Returns the norm of the complex number as well. #[inline] pub fn from_complex_and_get(q: Complex) -> (Self, N) { let norm = (q.im * q.im + q.re * q.re).sqrt(); @@ -69,25 +119,58 @@ impl UnitComplex { } /// Builds the unit complex number from the corresponding 2D rotation matrix. + /// + /// # Example + /// ``` + /// # use nalgebra::{Rotation2, UnitComplex}; + /// let rot = Rotation2::new(1.7); + /// let complex = UnitComplex::from_rotation_matrix(&rot); + /// assert_eq!(complex, UnitComplex::new(1.7)); + /// ``` + // FIXME: add UnitComplex::from(...) instead? #[inline] - pub fn from_rotation_matrix(rotmat: &Rotation) -> Self - where DefaultAllocator: Allocator { + pub fn from_rotation_matrix(rotmat: &Rotation2) -> Self { Self::new_unchecked(Complex::new(rotmat[(0, 0)], rotmat[(1, 0)])) } /// The unit complex needed to make `a` and `b` be collinear and point toward the same /// direction. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::{Vector2, UnitComplex}; + /// let a = Vector2::new(1.0, 2.0); + /// let b = Vector2::new(2.0, 1.0); + /// let rot = UnitComplex::rotation_between(&a, &b); + /// assert_relative_eq!(rot * a, b); + /// assert_relative_eq!(rot.inverse() * b, a); + /// ``` #[inline] pub fn rotation_between(a: &Vector, b: &Vector) -> Self where - SB: Storage, - SC: Storage, + SB: Storage, + SC: Storage, { Self::scaled_rotation_between(a, b, N::one()) } /// The smallest rotation needed to make `a` and `b` collinear and point toward the same /// direction, raised to the power `s`. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::{Vector2, UnitComplex}; + /// let a = Vector2::new(1.0, 2.0); + /// let b = Vector2::new(2.0, 1.0); + /// let rot2 = UnitComplex::scaled_rotation_between(&a, &b, 0.2); + /// let rot5 = UnitComplex::scaled_rotation_between(&a, &b, 0.5); + /// assert_relative_eq!(rot2 * rot2 * rot2 * rot2 * rot2 * a, b, epsilon = 1.0e-6); + /// assert_relative_eq!(rot5 * rot5 * a, b, epsilon = 1.0e-6); + /// ``` #[inline] pub fn scaled_rotation_between( a: &Vector, @@ -95,8 +178,8 @@ impl UnitComplex { s: N, ) -> Self where - SB: Storage, - SC: Storage, + SB: Storage, + SC: Storage, { // FIXME: code duplication with Rotation. if let (Some(na), Some(nb)) = ( @@ -111,6 +194,18 @@ impl UnitComplex { /// The unit complex needed to make `a` and `b` be collinear and point toward the same /// direction. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::{Unit, Vector2, UnitComplex}; + /// let a = Unit::new_normalize(Vector2::new(1.0, 2.0)); + /// let b = Unit::new_normalize(Vector2::new(2.0, 1.0)); + /// let rot = UnitComplex::rotation_between_axis(&a, &b); + /// assert_relative_eq!(rot * a, b); + /// assert_relative_eq!(rot.inverse() * b, a); + /// ``` #[inline] pub fn rotation_between_axis( a: &Unit>, @@ -125,6 +220,19 @@ impl UnitComplex { /// The smallest rotation needed to make `a` and `b` collinear and point toward the same /// direction, raised to the power `s`. + /// + /// # Example + /// ``` + /// # #[macro_use] extern crate approx; + /// # extern crate nalgebra; + /// # use nalgebra::{Unit, Vector2, UnitComplex}; + /// let a = Unit::new_normalize(Vector2::new(1.0, 2.0)); + /// let b = Unit::new_normalize(Vector2::new(2.0, 1.0)); + /// let rot2 = UnitComplex::scaled_rotation_between_axis(&a, &b, 0.2); + /// let rot5 = UnitComplex::scaled_rotation_between_axis(&a, &b, 0.5); + /// assert_relative_eq!(rot2 * rot2 * rot2 * rot2 * rot2 * a, b, epsilon = 1.0e-6); + /// assert_relative_eq!(rot5 * rot5 * a, b, epsilon = 1.0e-6); + /// ``` #[inline] pub fn scaled_rotation_between_axis( na: &Unit>,