Add doc-tests for several matrix construction methods.

src/base/construction.rs

@@ -175,6 +175,18 @@ where
     ///
     /// Panics if not enough rows are provided (for statically-sized matrices), or if all rows do
     /// not have the same dimensions.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{RowVector3, Matrix3};
+    /// # use std::iter;
+    ///
+    /// let m = Matrix3::from_rows(&[ RowVector3::new(1.0, 2.0, 3.0),  RowVector3::new(4.0, 5.0, 6.0),  RowVector3::new(7.0, 8.0, 9.0) ]);
+    ///
+    /// assert!(m.m11 == 1.0 && m.m12 == 2.0 && m.m13 == 3.0 &&
+    ///         m.m21 == 4.0 && m.m22 == 5.0 && m.m23 == 6.0 &&
+    ///         m.m31 == 7.0 && m.m32 == 8.0 && m.m33 == 9.0);
+    /// ```
     #[inline]
     pub fn from_rows<SB>(rows: &[Matrix<N, U1, C, SB>]) -> Self
     where
@@ -205,6 +217,18 @@ where
     ///
     /// Panics if not enough columns are provided (for statically-sized matrices), or if all
     /// columns do not have the same dimensions.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Vector3, Matrix3};
+    /// # use std::iter;
+    ///
+    /// let m = Matrix3::from_columns(&[ Vector3::new(1.0, 2.0, 3.0),  Vector3::new(4.0, 5.0, 6.0),  Vector3::new(7.0, 8.0, 9.0) ]);
+    ///
+    /// assert!(m.m11 == 1.0 && m.m12 == 4.0 && m.m13 == 7.0 &&
+    ///         m.m21 == 2.0 && m.m22 == 5.0 && m.m23 == 8.0 &&
+    ///         m.m31 == 3.0 && m.m32 == 6.0 && m.m33 == 9.0);
+    /// ```
     #[inline]
     pub fn from_columns<SB>(columns: &[Vector<N, R, SB>]) -> Self
     where
@@ -259,6 +283,23 @@ where
     DefaultAllocator: Allocator<N, D, D>,
 {
     /// Creates a square matrix with its diagonal set to `diag` and all other entries set to 0.
+    ///
+    /// # Example
+    /// ```
+    /// # use nalgebra::{Vector3, DVector, Matrix3, DMatrix};
+    /// # use std::iter;
+    ///
+    /// let m = Matrix3::from_diagonal(&Vector3::new(1.0, 2.0, 3.0));
+    /// // The two additional arguments represent the matrix dimensions.
+    /// let dm = DMatrix::from_diagonal(&DVector::from_row_slice(3, &[1.0, 2.0, 3.0]));
+    ///
+    /// assert!(m.m11 == 1.0 && m.m12 == 0.0 && m.m13 == 0.0 &&
+    ///         m.m21 == 0.0 && m.m22 == 2.0 && m.m23 == 0.0 &&
+    ///         m.m31 == 0.0 && m.m32 == 0.0 && m.m33 == 3.0);
+    /// assert!(dm[(0, 0)] == 1.0 && dm[(0, 1)] == 0.0 && dm[(0, 2)] == 0.0 &&
+    ///         dm[(1, 0)] == 0.0 && dm[(1, 1)] == 2.0 && dm[(1, 2)] == 0.0 &&
+    ///         dm[(2, 0)] == 0.0 && dm[(2, 1)] == 0.0 && dm[(2, 2)] == 3.0);
+    /// ```
     #[inline]
     pub fn from_diagonal<SB: Storage<N, D>>(diag: &Vector<N, D, SB>) -> Self
     where
@@ -287,34 +328,113 @@ macro_rules! impl_constructors(
         impl<N: Scalar, $($DimIdent: $DimBound, )*> MatrixMN<N $(, $Dims)*>
             where DefaultAllocator: Allocator<N $(, $Dims)*> {
 
-            /// Creates a new uninitialized matrix.
+            /// Creates a new uninitialized matrix or vector.
             #[inline]
             pub unsafe fn new_uninitialized($($args: usize),*) -> Self {
                 Self::new_uninitialized_generic($($gargs),*)
             }
 
-            /// Creates a matrix with all its elements set to `elem`.
+            /// Creates a matrix or vector with all its elements set to `elem`.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            ///
+            /// let v = Vector3::from_element(2.0);
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::from_element(3, 2.0);
+            /// let m = Matrix2x3::from_element(2.0);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_element(2, 3, 2.0);
+            ///
+            /// assert!(v.x == 2.0 && v.y == 2.0 && v.z == 2.0);
+            /// assert!(dv[0] == 2.0 && dv[1] == 2.0 && dv[2] == 2.0);
+            /// assert!(m.m11 == 2.0 && m.m12 == 2.0 && m.m13 == 2.0 &&
+            ///         m.m21 == 2.0 && m.m22 == 2.0 && m.m23 == 2.0);
+            /// assert!(dm[(0, 0)] == 2.0 && dm[(0, 1)] == 2.0 && dm[(0, 2)] == 2.0 &&
+            ///         dm[(1, 0)] == 2.0 && dm[(1, 1)] == 2.0 && dm[(1, 2)] == 2.0);
+            /// ```
             #[inline]
             pub fn from_element($($args: usize,)* elem: N) -> Self {
                 Self::from_element_generic($($gargs, )* elem)
             }
 
-            /// Creates a matrix with all its elements set to `elem`.
+            /// Creates a matrix or vector with all its elements set to `elem`.
             ///
             /// Same as `.from_element`.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            ///
+            /// let v = Vector3::repeat(2.0);
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::repeat(3, 2.0);
+            /// let m = Matrix2x3::repeat(2.0);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::repeat(2, 3, 2.0);
+            ///
+            /// assert!(v.x == 2.0 && v.y == 2.0 && v.z == 2.0);
+            /// assert!(dv[0] == 2.0 && dv[1] == 2.0 && dv[2] == 2.0);
+            /// assert!(m.m11 == 2.0 && m.m12 == 2.0 && m.m13 == 2.0 &&
+            ///         m.m21 == 2.0 && m.m22 == 2.0 && m.m23 == 2.0);
+            /// assert!(dm[(0, 0)] == 2.0 && dm[(0, 1)] == 2.0 && dm[(0, 2)] == 2.0 &&
+            ///         dm[(1, 0)] == 2.0 && dm[(1, 1)] == 2.0 && dm[(1, 2)] == 2.0);
+            /// ```
             #[inline]
             pub fn repeat($($args: usize,)* elem: N) -> Self {
                 Self::repeat_generic($($gargs, )* elem)
             }
 
-            /// Creates a matrix with all its elements set to `0`.
+            /// Creates a matrix or vector with all its elements set to `0`.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            ///
+            /// let v = Vector3::<f32>::zeros();
+            /// // The argument represents the vector dimension.
+            /// let dv = DVector::<f32>::zeros(3);
+            /// let m = Matrix2x3::<f32>::zeros();
+            /// // The two arguments represent the matrix dimensions.
+            /// let dm = DMatrix::<f32>::zeros(2, 3);
+            ///
+            /// assert!(v.x == 0.0 && v.y == 0.0 && v.z == 0.0);
+            /// assert!(dv[0] == 0.0 && dv[1] == 0.0 && dv[2] == 0.0);
+            /// assert!(m.m11 == 0.0 && m.m12 == 0.0 && m.m13 == 0.0 &&
+            ///         m.m21 == 0.0 && m.m22 == 0.0 && m.m23 == 0.0);
+            /// assert!(dm[(0, 0)] == 0.0 && dm[(0, 1)] == 0.0 && dm[(0, 2)] == 0.0 &&
+            ///         dm[(1, 0)] == 0.0 && dm[(1, 1)] == 0.0 && dm[(1, 2)] == 0.0);
+            /// ```
             #[inline]
             pub fn zeros($($args: usize),*) -> Self
                 where N: Zero {
                 Self::zeros_generic($($gargs),*)
             }
 
-            /// Creates a matrix with all its elements filled by an iterator.
+            /// Creates a matrix or vector with all its elements filled by an iterator.
+            ///
+            /// The output matrix is filled column-by-column.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let v = Vector3::from_iterator((0..3).into_iter());
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::from_iterator(3, (0..3).into_iter());
+            /// let m = Matrix2x3::from_iterator((0..6).into_iter());
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_iterator(2, 3, (0..6).into_iter());
+            ///
+            /// assert!(v.x == 0 && v.y == 1 && v.z == 2);
+            /// assert!(dv[0] == 0 && dv[1] == 1 && dv[2] == 2);
+            /// assert!(m.m11 == 0 && m.m12 == 2 && m.m13 == 4 &&
+            ///         m.m21 == 1 && m.m22 == 3 && m.m23 == 5);
+            /// assert!(dm[(0, 0)] == 0 && dm[(0, 1)] == 2 && dm[(0, 2)] == 4 &&
+            ///         dm[(1, 0)] == 1 && dm[(1, 1)] == 3 && dm[(1, 2)] == 5);
+            /// ```
             #[inline]
             pub fn from_iterator<I>($($args: usize,)* iter: I) -> Self
                 where I: IntoIterator<Item = N> {
@@ -326,6 +446,26 @@ macro_rules! impl_constructors(
             ///
             /// The order of elements in the slice must follow the usual mathematic writing, i.e.,
             /// row-by-row.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let v = Vector3::from_row_slice(&[0, 1, 2]);
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::from_row_slice(3, &[0, 1, 2]);
+            /// let m = Matrix2x3::from_row_slice(&[0, 1, 2, 3, 4, 5]);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_row_slice(2, 3, &[0, 1, 2, 3, 4, 5]);
+            ///
+            /// assert!(v.x == 0 && v.y == 1 && v.z == 2);
+            /// assert!(dv[0] == 0 && dv[1] == 1 && dv[2] == 2);
+            /// assert!(m.m11 == 0 && m.m12 == 1 && m.m13 == 2 &&
+            ///         m.m21 == 3 && m.m22 == 4 && m.m23 == 5);
+            /// assert!(dm[(0, 0)] == 0 && dm[(0, 1)] == 1 && dm[(0, 2)] == 2 &&
+            ///         dm[(1, 0)] == 3 && dm[(1, 1)] == 4 && dm[(1, 2)] == 5);
+            /// ```
             #[inline]
             pub fn from_row_slice($($args: usize,)* slice: &[N]) -> Self {
                 Self::from_row_slice_generic($($gargs, )* slice)
@@ -333,14 +473,53 @@ macro_rules! impl_constructors(
 
             /// Creates a matrix with its elements filled with the components provided by a slice
             /// in column-major order.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let v = Vector3::from_column_slice(&[0, 1, 2]);
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::from_column_slice(3, &[0, 1, 2]);
+            /// let m = Matrix2x3::from_column_slice(&[0, 1, 2, 3, 4, 5]);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_column_slice(2, 3, &[0, 1, 2, 3, 4, 5]);
+            ///
+            /// assert!(v.x == 0 && v.y == 1 && v.z == 2);
+            /// assert!(dv[0] == 0 && dv[1] == 1 && dv[2] == 2);
+            /// assert!(m.m11 == 0 && m.m12 == 2 && m.m13 == 4 &&
+            ///         m.m21 == 1 && m.m22 == 3 && m.m23 == 5);
+            /// assert!(dm[(0, 0)] == 0 && dm[(0, 1)] == 2 && dm[(0, 2)] == 4 &&
+            ///         dm[(1, 0)] == 1 && dm[(1, 1)] == 3 && dm[(1, 2)] == 5);
+            /// ```
             #[inline]
             pub fn from_column_slice($($args: usize,)* slice: &[N]) -> Self {
                 Self::from_column_slice_generic($($gargs, )* slice)
             }
 
-            /// Creates a matrix filled with the results of a function applied to each of its
+            /// Creates a matrix or vector filled with the results of a function applied to each of its
             /// component coordinates.
-            // FIXME: don't take a dimension of the matrix is statically sized.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, Vector3, DVector, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let v = Vector3::from_fn(|i, _| i);
+            /// // The additional argument represents the vector dimension.
+            /// let dv = DVector::from_fn(3, |i, _| i);
+            /// let m = Matrix2x3::from_fn(|i, j| i * 3 + j);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_fn(2, 3, |i, j| i * 3 + j);
+            ///
+            /// assert!(v.x == 0 && v.y == 1 && v.z == 2);
+            /// assert!(dv[0] == 0 && dv[1] == 1 && dv[2] == 2);
+            /// assert!(m.m11 == 0 && m.m12 == 1 && m.m13 == 2 &&
+            ///         m.m21 == 3 && m.m22 == 4 && m.m23 == 5);
+            /// assert!(dm[(0, 0)] == 0 && dm[(0, 1)] == 1 && dm[(0, 2)] == 2 &&
+            ///         dm[(1, 0)] == 3 && dm[(1, 1)] == 4 && dm[(1, 2)] == 5);
+            /// ```
             #[inline]
             pub fn from_fn<F>($($args: usize,)* f: F) -> Self
                 where F: FnMut(usize, usize) -> N {
@@ -350,6 +529,21 @@ macro_rules! impl_constructors(
             /// Creates an identity matrix. If the matrix is not square, the largest square
             /// submatrix (starting at the first row and column) is set to the identity while all
             /// other entries are set to zero.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let m = Matrix2x3::<f32>::identity();
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::<f32>::identity(2, 3);
+            ///
+            /// assert!(m.m11 == 1.0 && m.m12 == 0.0 && m.m13 == 0.0 &&
+            ///         m.m21 == 0.0 && m.m22 == 1.0 && m.m23 == 0.0);
+            /// assert!(dm[(0, 0)] == 1.0 && dm[(0, 1)] == 0.0 && dm[(0, 2)] == 0.0 &&
+            ///         dm[(1, 0)] == 0.0 && dm[(1, 1)] == 1.0 && dm[(1, 2)] == 0.0);
+            /// ```
             #[inline]
             pub fn identity($($args: usize,)*) -> Self
                 where N: Zero + One {
@@ -358,6 +552,21 @@ macro_rules! impl_constructors(
 
             /// Creates a matrix filled with its diagonal filled with `elt` and all other
             /// components set to zero.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix2x3, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let m = Matrix2x3::from_diagonal_element(5.0);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_diagonal_element(2, 3, 5.0);
+            ///
+            /// assert!(m.m11 == 5.0 && m.m12 == 0.0 && m.m13 == 0.0 &&
+            ///         m.m21 == 0.0 && m.m22 == 5.0 && m.m23 == 0.0);
+            /// assert!(dm[(0, 0)] == 5.0 && dm[(0, 1)] == 0.0 && dm[(0, 2)] == 0.0 &&
+            ///         dm[(1, 0)] == 0.0 && dm[(1, 1)] == 5.0 && dm[(1, 2)] == 0.0);
+            /// ```
             #[inline]
             pub fn from_diagonal_element($($args: usize,)* elt: N) -> Self
                 where N: Zero + One {
@@ -368,13 +577,30 @@ macro_rules! impl_constructors(
             /// elements are filled with the content of `elts`. Others are set to 0.
             ///
             /// Panics if `elts.len()` is larger than the minimum among `nrows` and `ncols`.
+            ///
+            /// # Example
+            /// ```
+            /// # use nalgebra::{Matrix3, DMatrix};
+            /// # use std::iter;
+            ///
+            /// let m = Matrix3::from_partial_diagonal(&[1.0, 2.0]);
+            /// // The two additional arguments represent the matrix dimensions.
+            /// let dm = DMatrix::from_partial_diagonal(3, 3, &[1.0, 2.0]);
+            ///
+            /// assert!(m.m11 == 1.0 && m.m12 == 0.0 && m.m13 == 0.0 &&
+            ///         m.m21 == 0.0 && m.m22 == 2.0 && m.m23 == 0.0 &&
+            ///         m.m31 == 0.0 && m.m32 == 0.0 && m.m33 == 0.0);
+            /// assert!(dm[(0, 0)] == 1.0 && dm[(0, 1)] == 0.0 && dm[(0, 2)] == 0.0 &&
+            ///         dm[(1, 0)] == 0.0 && dm[(1, 1)] == 2.0 && dm[(1, 2)] == 0.0 &&
+            ///         dm[(2, 0)] == 0.0 && dm[(2, 1)] == 0.0 && dm[(2, 2)] == 0.0);
+            /// ```
             #[inline]
             pub fn from_partial_diagonal($($args: usize,)* elts: &[N]) -> Self
                 where N: Zero {
                 Self::from_partial_diagonal_generic($($gargs, )* elts)
             }
 
-            /// Creates a matrix filled with random values from the given distribution.
+            /// Creates a matrix or vector filled with random values from the given distribution.
             #[inline]
             pub fn from_distribution<Distr: Distribution<N> + ?Sized, G: Rng + ?Sized>(
                 $($args: usize,)*