Added a more convenient way to initialize a matrix using the operator<<.

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

dlib/matrix/matrix.h

@@ -1426,6 +1426,59 @@ namespace dlib
         }
 
     private:
+        struct literal_assign_helper
+        {
+            /*
+                This struct is a helper struct returned by the operator<<() function below.  It is
+                used primarily to enable us to put DLIB_CASSERT statements on the usage of the
+                operator<< form of matrix assignment.
+            */
+
+            literal_assign_helper(const literal_assign_helper& item) : m(item.m), r(item.r), c(item.c), is_copy(true) {}
+            literal_assign_helper(matrix* m_): m(m_), r(0), c(0),is_copy(false) {}
+            ~literal_assign_helper()
+            {
+                DLIB_CASSERT(!is_copy || r == m->nr(),
+                             "You have used the matrix operator<< assignment incorrectly by failing to\n"
+                             "supply a full set of values for every element of a matrix object.\n");
+            }
+
+            template <typename U>
+            const literal_assign_helper& operator, (
+                const U& val
+            ) const
+            {
+                DLIB_CASSERT(r < m->nr() && c < m->nc(),
+                             "You have used the matrix operator<< assignment incorrectly by attempting to\n" <<
+                             "supply more values than there are elements in the matrix object being assigned to.\n\n" <<
+                             "Did you forget to call set_size()?\n");
+                (*m)(r,c) = static_cast<T>(val);
+                ++c;
+                if (c == m->nc())
+                {
+                    c = 0;
+                    ++r;
+                }
+                return *this;
+            }
+
+
+            bool is_copy;
+            matrix* m;
+            mutable long r;
+            mutable long c;
+        };
+
+    public:
+
+        template <typename U>
+        const literal_assign_helper operator << (
+            const U& val
+        ) { return literal_assign_helper(this) , val; }
+
+    private:
+
+
         typename layout::template layout<T,NR,NC,mem_manager> data;
     };
 

dlib/matrix/matrix_abstract.h

@@ -750,6 +750,27 @@ namespace dlib
                 - returns *this
         !*/
 
+        template <typename U>
+        const literal_assign_helper operator << (
+            const U& val
+        );
+        /*!
+            This function is somewhat different than all the others defined in this file.
+            The purpose of this function is to enable you to easily initialize a matrix object.
+            For example:
+                matrix<double> m(2,3);
+                m << 1,2,3,
+                     4,5,6;
+
+            The above code creates a matrix m with 2 rows and 3 columns and sets it so that
+            it contains the matrix | 1 2 3 |
+                                   | 4 5 6 |
+
+            To use this method of assignment it is required that you supply exactly m.size()
+            values so that the matrix is fully initialized.  Supplying fewer or more than
+            that is an error that will cause a dlib::fatal_error to be thrown.
+        !*/
+
         void swap (
             matrix& item
         );