Added the diagm(), svd2() and svd3() functions.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%402627

dlib/matrix/matrix_utilities_abstract.h

@@ -29,6 +29,20 @@ namespace dlib
               of m in the order R(0)==m(0,0), R(1)==m(1,1), R(2)==m(2,2) and so on.
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    const matrix_exp diagm (
+        const matrix_exp& m
+    );
+    /*!
+        requires
+            - m is a row or column matrix
+        ensures
+            - returns a square matrix M such that:
+                - diag(M) == m
+                - non diagonal elements of M are 0
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     const matrix_exp trans (
@@ -730,7 +744,7 @@ namespace dlib
             - m == #u*#w*trans(#v)
             - trans(#u)*#u == identity matrix
             - trans(#v)*#v == identity matrix
-            - diag(#w) == the sinular values of the matrix m in no 
+            - diag(#w) == the singular values of the matrix m in no 
               particular order.  All non-diagonal elements of #w are
               set to 0.
             - #u.nr() == m.nr()
@@ -741,6 +755,67 @@ namespace dlib
             - #v.nc() == m.nc()
     !*/
 
+// ----------------------------------------------------------------------------------------
+
+    long svd2 (
+        bool withu, 
+        bool withv, 
+        const matrix_exp& m,
+        matrix<matrix_exp::type>& u,
+        matrix<matrix_exp::type>& w,
+        matrix<matrix_exp::type>& v
+    );
+    /*!
+        requires
+            - a.nr() >= a.nc()
+        ensures
+            - computes the singular value decomposition of matrix a
+            - a == subm(#u,get_rect(a))*diagm(#w)*trans(#v)
+            - trans(#u)*#u == identity matrix
+            - trans(#v)*#v == identity matrix
+            - #w == the singular values of the matrix m in no 
+              particular order.  
+            - #u.nr() == m.nr()
+            - #u.nc() == m.nr()
+            - #w.nr() == m.nc()
+            - #w.nc() == 1 
+            - #v.nr() == m.nc()
+            - #v.nc() == m.nc()
+            - if (widthu == false) then
+                - ignore the above regarding #u, it isn't computed and its
+                  output state is undefined.
+            - if (widthv == false) then
+                - ignore the above regarding #v, it isn't computed and its
+                  output state is undefined.
+            - returns an error code of 0, if no errors and 'k' if we fail to
+              converge at the 'kth' singular value.
+    !*/
+
+// ----------------------------------------------------------------------------------------
+
+    void svd3 (
+        const matrix_exp& m,
+        matrix<matrix_exp::type>& u,
+        matrix<matrix_exp::type>& w,
+        matrix<matrix_exp::type>& v
+    );
+    /*!
+        ensures
+            - computes the singular value decomposition of m
+            - m == #u*diagm(#w)*trans(#v)
+            - trans(#u)*#u == identity matrix
+            - trans(#v)*#v == identity matrix
+            - #w == the singular values of the matrix m in no 
+              particular order.  All non-diagonal elements of #w are
+              set to 0.
+            - #u.nr() == m.nr()
+            - #u.nc() == m.nc()
+            - #w.nr() == m.nc()
+            - #w.nc() == 1 
+            - #v.nr() == m.nc()
+            - #v.nc() == m.nc()
+    !*/
+
 // ----------------------------------------------------------------------------------------
 
     const matrix_exp::type det (