diff --git a/src/base/construction.rs b/src/base/construction.rs index 652b3eb6..81e5f935 100644 --- a/src/base/construction.rs +++ b/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(rows: &[Matrix]) -> 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(columns: &[Vector]) -> Self where @@ -259,6 +283,23 @@ where DefaultAllocator: Allocator, { /// 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>(diag: &Vector) -> Self where @@ -287,34 +328,113 @@ macro_rules! impl_constructors( impl MatrixMN where DefaultAllocator: Allocator { - /// 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::::zeros(); + /// // The argument represents the vector dimension. + /// let dv = DVector::::zeros(3); + /// let m = Matrix2x3::::zeros(); + /// // The two arguments represent the matrix dimensions. + /// let dm = DMatrix::::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($($args: usize,)* iter: I) -> Self where I: IntoIterator { @@ -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($($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::::identity(); + /// // The two additional arguments represent the matrix dimensions. + /// let dm = DMatrix::::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 + ?Sized, G: Rng + ?Sized>( $($args: usize,)*