<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - matrix_expressions_ex.cpp</title></head><body bgcolor='white'><pre>
<font color='#009900'>// The contents of this file are in the public domain. See LICENSE_FOR_EXAMPLE_PROGRAMS.txt
</font>
<font color='#009900'>/*
    This example contains a detailed discussion of the template expression
    technique used to implement the matrix tools in the dlib C++ library.

    It also gives examples showing how a user can create their own custom
    matrix expressions.

    Note that you should be familiar with the dlib::matrix before reading
    this example.  So if you haven't done so already you should read the
    matrix_ex.cpp example program.
*/</font>


<font color='#0000FF'>#include</font> <font color='#5555FF'>&lt;</font>iostream<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>#include</font> <font color='#5555FF'>&lt;</font>dlib<font color='#5555FF'>/</font>matrix.h<font color='#5555FF'>&gt;</font>

<font color='#0000FF'>using</font> <font color='#0000FF'>namespace</font> dlib;
<font color='#0000FF'>using</font> <font color='#0000FF'>namespace</font> std;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'><u>void</u></font> <b><a name='custom_matrix_expressions_example'></a>custom_matrix_expressions_example</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'><u>int</u></font> <b><a name='main'></a>main</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>
<b>{</b>

    <font color='#009900'>// Declare some variables used below
</font>    matrix<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>double</u></font>,<font color='#979000'>3</font>,<font color='#979000'>1</font><font color='#5555FF'>&gt;</font> y;
    matrix<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>double</u></font>,<font color='#979000'>3</font>,<font color='#979000'>3</font><font color='#5555FF'>&gt;</font> M;
    matrix<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>double</u></font><font color='#5555FF'>&gt;</font> x;

    <font color='#009900'>// set all elements to 1
</font>    y <font color='#5555FF'>=</font> <font color='#979000'>1</font>;
    M <font color='#5555FF'>=</font> <font color='#979000'>1</font>;
    

    <font color='#009900'>// -------------------------  Template Expressions -----------------------------
</font>    <font color='#009900'>// Now I will discuss the "template expressions" technique and how it is 
</font>    <font color='#009900'>// used in the matrix object.  First consider the following expression:
</font>    x <font color='#5555FF'>=</font> y <font color='#5555FF'>+</font> y;

    <font color='#009900'>/*
        Normally this expression results in machine code that looks, at a high 
        level, like the following:
            temp = y + y;
            x = temp

        Temp is a temporary matrix returned by the overloaded + operator.  
        temp then contains the result of adding y to itself.  The assignment 
        operator copies the value of temp into x and temp is then destroyed while 
        the blissful C++ user never sees any of this.

        This is, however, totally inefficient.  In the process described above 
        you have to pay for the cost of constructing a temporary matrix object
        and allocating its memory.  Then you pay the additional cost of copying
        it over to x.  It also gets worse when you have more complex expressions
        such as x = round(y + y + y + M*y) which would involve the creation and copying 
        of 5 temporary matrices.  
        
        All these inefficiencies are removed by using the template expressions 
        technique.  The basic idea is as follows, instead of having operators and 
        functions return temporary matrix objects you return a special object that 
        represents the expression you wish to perform.

        So consider the expression x = y + y again.  With dlib::matrix what happens
        is the expression y+y returns a matrix_exp object instead of a temporary matrix.
        The construction of a matrix_exp does not allocate any memory or perform any 
        computations.  The matrix_exp however has an interface that looks just like a 
        dlib::matrix object and when you ask it for the value of one of its elements 
        it computes that value on the spot.  Only in the assignment operator does
        someone ask the matrix_exp for these values so this avoids the use of any
        temporary matrices.  Thus the statement x = y + y is equivalent to the following 
        code:
            // loop over all elements in y matrix
            for (long r = 0; r &lt; y.nr(); ++r)
                for (long c = 0; c &lt; y.nc(); ++c)
                    x(r,c) = y(r,c) + y(r,c);  
                
       
        This technique works for expressions of arbitrary complexity.  So if you 
        typed x = round(y + y + y + M*y) it would involve no temporary matrices being 
        created at all.  Each operator takes and returns only matrix_exp objects.
        Thus, no computations are performed until the assignment operator requests
        the values from the matrix_exp it receives as input. 
            




        There is, however, a slight complication in all of this.  It is for statements 
        that involve the multiplication of a complex matrix_exp such as the following:
    */</font>
        x <font color='#5555FF'>=</font> M<font color='#5555FF'>*</font><font face='Lucida Console'>(</font>M<font color='#5555FF'>+</font>M<font color='#5555FF'>+</font>M<font color='#5555FF'>+</font>M<font color='#5555FF'>+</font>M<font color='#5555FF'>+</font>M<font color='#5555FF'>+</font>M<font face='Lucida Console'>)</font>;
    <font color='#009900'>/*
        According to the discussion above, this statement would compute the value of 
        M*(M+M+M+M+M+M+M) totally without any temporary matrix objects.  This sounds 
        good but we should take a closer look.  Consider that the + operator is 
        invoked 6 times.  This means we have something like this:

        x = M * (matrix_exp representing M+M+M+M+M+M+M);

        M is being multiplied with a quite complex matrix_exp.  Now recall that when 
        you ask a matrix_exp what the value of any of its elements are it computes 
        their values *right then*.  
        
        If you think on what is involved in performing a matrix multiply you will 
        realize that each element of a matrix is accessed M.nr() times.  In the 
        case of our above expression the cost of accessing an element of the 
        matrix_exp on the right hand side is the cost of doing 6 addition operations. 

        Thus, it would be faster to assign M+M+M+M+M+M+M to a temporary matrix and then
        multiply that by M.  This is exactly what the dlib::matrix does under the covers.  
        This is because it is able to spot expressions where the introduction of a 
        temporary is needed to speed up the computation and it will automatically do this 
        for you.  



        
        Another complication that is dealt with automatically is aliasing.  All matrix 
        expressions are said to "alias" their contents.  For example, consider
        the following expressions:
           M + M
           M * M 

        We say that the expressions (M + M) and (M * M) alias M.  Additionally, we say that
        the expression (M * M) destructively aliases M.    

        To understand why we say (M * M) destructively aliases M consider what would happen
        if we attempted to evaluate it without first assigning (M * M) to a temporary matrix.
        That is, if we attempted to perform the following:
            for (long r = 0; r &lt; M.nr(); ++r)
                for (long c = 0; c &lt; M.nc(); ++c)
                    M(r,c) = rowm(M,r)*colm(M,c);  

        It is clear that the result would be corrupted and M wouldn't end up with the right
        values in it.  So in this case we must perform the following:
            temp = M*M;
            M = temp;

        This sort of interaction is what defines destructive aliasing.  Whenever we are
        assigning a matrix expression to a destination that is destructively aliased by
        the expression we need to introduce a temporary.  The dlib::matrix is capable of 
        recognizing the two forms of aliasing and introduces temporary matrices only when 
        necessary.
    */</font>



    <font color='#009900'>// Next we discuss how to create custom matrix expressions.   In what follows we 
</font>    <font color='#009900'>// will define three different matrix expressions and show their use.  
</font>    <font color='#BB00BB'>custom_matrix_expressions_example</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>;
<b>}</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font><font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> M<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>struct</font> <b><a name='example_op_trans'></a>example_op_trans</b> 
<b>{</b>
    <font color='#009900'>/*!
        This object defines a matrix expression that represents a transposed matrix.
        As discussed above, constructing this object doesn't compute anything.  It just
        holds a reference to a matrix and presents an interface which defines
        matrix transposition.   
    !*/</font>

    <font color='#009900'>// Here we simply hold a reference to the matrix we are supposed to be the transpose of.
</font>    <b><a name='example_op_trans'></a>example_op_trans</b><font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> M<font color='#5555FF'>&amp;</font> m_<font face='Lucida Console'>)</font> : m<font face='Lucida Console'>(</font>m_<font face='Lucida Console'>)</font><b>{</b><b>}</b>
    <font color='#0000FF'>const</font> M<font color='#5555FF'>&amp;</font> m;

    <font color='#009900'>// The cost field is used by matrix multiplication code to decide if a temporary needs to 
</font>    <font color='#009900'>// be introduced.  It represents the computational cost of evaluating an element of the
</font>    <font color='#009900'>// matrix expression.  In this case we say that the cost of obtaining an element of the
</font>    <font color='#009900'>// transposed matrix is the same as obtaining an element of the original matrix (since
</font>    <font color='#009900'>// transpose doesn't really compute anything).
</font>    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> cost <font color='#5555FF'>=</font> M::cost;

    <font color='#009900'>// Here we define the matrix expression's compile-time known dimensions.  Since this
</font>    <font color='#009900'>// is a transpose we define them to be the reverse of M's dimensions.
</font>    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NR <font color='#5555FF'>=</font> M::NC;
    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NC <font color='#5555FF'>=</font> M::NR;

    <font color='#009900'>// Define the type of element in this matrix expression.  Also define the 
</font>    <font color='#009900'>// memory manager type used and the layout.  Usually we use the same types as the
</font>    <font color='#009900'>// input matrix.
</font>    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::type type;
    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::mem_manager_type mem_manager_type;
    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::layout_type layout_type;

    <font color='#009900'>// This is where the action is.  This function is what defines the value of an element of
</font>    <font color='#009900'>// this matrix expression.  Here we are saying that m(c,r) == trans(m)(r,c) which is just
</font>    <font color='#009900'>// the definition of transposition.  Note also that we must define the return type from this
</font>    <font color='#009900'>// function as a typedef.  This typedef lets us either return our argument by value or by
</font>    <font color='#009900'>// reference.  In this case we use the same type as the underlying m matrix.  Later in this
</font>    <font color='#009900'>// example program you will see two other options.
</font>    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::const_ret_type const_ret_type;
    const_ret_type <b><a name='apply'></a>apply</b> <font face='Lucida Console'>(</font><font color='#0000FF'><u>long</u></font> r, <font color='#0000FF'><u>long</u></font> c<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> <font color='#BB00BB'>m</font><font face='Lucida Console'>(</font>c,r<font face='Lucida Console'>)</font>; <b>}</b>

    <font color='#009900'>// Define the run-time defined dimensions of this matrix.  
</font>    <font color='#0000FF'><u>long</u></font> <b><a name='nr'></a>nr</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>nc</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#0000FF'><u>long</u></font> <b><a name='nc'></a>nc</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>nr</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>; <b>}</b>

    <font color='#009900'>// Recall the discussion of aliasing.  Each matrix expression needs to define what
</font>    <font color='#009900'>// kind of aliasing it introduces so that we know when to introduce temporaries.  The 
</font>    <font color='#009900'>// aliases() function indicates that the matrix transpose expression aliases item if
</font>    <font color='#009900'>// and only if the m matrix aliases item.  
</font>    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='aliases'></a>aliases</b>               <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>aliases</font><font face='Lucida Console'>(</font>item<font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#009900'>// This next function indicates that the matrix transpose expression also destructively 
</font>    <font color='#009900'>// aliases anything m aliases.  I.e. transpose has destructive aliasing.
</font>    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='destructively_aliases'></a>destructively_aliases</b> <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>aliases</font><font face='Lucida Console'>(</font>item<font face='Lucida Console'>)</font>; <b>}</b>

<b>}</b>; 


<font color='#009900'>// Here we define a simple function that creates and returns transpose expressions.  Note that the
</font><font color='#009900'>// matrix_op&lt;&gt; template is a matrix_exp object and exists solely to reduce the amount of boilerplate
</font><font color='#009900'>// you have to write to create a matrix expression.
</font><font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font> <font color='#0000FF'>typename</font> M <font color='#5555FF'>&gt;</font>
<font color='#0000FF'>const</font> matrix_op<font color='#5555FF'>&lt;</font>example_op_trans<font color='#5555FF'>&lt;</font>M<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font> <b><a name='example_trans'></a>example_trans</b> <font face='Lucida Console'>(</font>
    <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>M<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> m
<font face='Lucida Console'>)</font>
<b>{</b>
    <font color='#0000FF'>typedef</font> example_op_trans<font color='#5555FF'>&lt;</font>M<font color='#5555FF'>&gt;</font> op;
    <font color='#009900'>// m.ref() returns a reference to the object of type M contained in the matrix expression m.
</font>    <font color='#0000FF'>return</font> matrix_op<font color='#5555FF'>&lt;</font>op<font color='#5555FF'>&gt;</font><font face='Lucida Console'>(</font><font color='#BB00BB'>op</font><font face='Lucida Console'>(</font>m.<font color='#BB00BB'>ref</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font><font face='Lucida Console'>)</font><font face='Lucida Console'>)</font>;
<b>}</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> T<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>struct</font> <b><a name='example_op_vector_to_matrix'></a>example_op_vector_to_matrix</b>  
<b>{</b>
    <font color='#009900'>/*!
        This object defines a matrix expression that holds a reference to a std::vector&lt;T&gt;
        and makes it look like a column vector.  Thus it enables you to use a std::vector
        as if it was a dlib::matrix.

    !*/</font>
    <b><a name='example_op_vector_to_matrix'></a>example_op_vector_to_matrix</b><font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> vect_<font face='Lucida Console'>)</font> : vect<font face='Lucida Console'>(</font>vect_<font face='Lucida Console'>)</font><b>{</b><b>}</b>

    <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> vect;

    <font color='#009900'>// This expression wraps direct memory accesses so we use the lowest possible cost. 
</font>    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> cost <font color='#5555FF'>=</font> <font color='#979000'>1</font>; 

    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NR <font color='#5555FF'>=</font> <font color='#979000'>0</font>; <font color='#009900'>// We don't know the length of the vector until runtime.  So we put 0 here.
</font>    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NC <font color='#5555FF'>=</font> <font color='#979000'>1</font>; <font color='#009900'>// We do know that it only has one column (since it's a vector)
</font>    <font color='#0000FF'>typedef</font> T type;
    <font color='#009900'>// Since the std::vector doesn't use a dlib memory manager we list the default one here.
</font>    <font color='#0000FF'>typedef</font> default_memory_manager mem_manager_type;
    <font color='#009900'>// The layout type also doesn't really matter in this case.  So we list row_major_layout
</font>    <font color='#009900'>// since it is a good default.
</font>    <font color='#0000FF'>typedef</font> row_major_layout layout_type;

    <font color='#009900'>// Note that we define const_ret_type to be a reference type.  This way we can
</font>    <font color='#009900'>// return the contents of the std::vector by reference.
</font>    <font color='#0000FF'>typedef</font> <font color='#0000FF'>const</font> T<font color='#5555FF'>&amp;</font> const_ret_type;
    const_ret_type <b><a name='apply'></a>apply</b> <font face='Lucida Console'>(</font><font color='#0000FF'><u>long</u></font> r, <font color='#0000FF'><u>long</u></font> <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> vect[r]; <b>}</b>

    <font color='#0000FF'><u>long</u></font> <b><a name='nr'></a>nr</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> vect.<font color='#BB00BB'>size</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#0000FF'><u>long</u></font> <b><a name='nc'></a>nc</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> <font color='#979000'>1</font>; <b>}</b>

    <font color='#009900'>// This expression never aliases anything since it doesn't contain any matrix expression (it 
</font>    <font color='#009900'>// contains only a std::vector which doesn't count since you can't assign a matrix expression
</font>    <font color='#009900'>// to a std::vector object).
</font>    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='aliases'></a>aliases</b>               <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> <font color='#979000'>false</font>; <b>}</b>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='destructively_aliases'></a>destructively_aliases</b> <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> <font color='#979000'>false</font>; <b>}</b>
<b>}</b>; 

<font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font> <font color='#0000FF'>typename</font> T <font color='#5555FF'>&gt;</font>
<font color='#0000FF'>const</font> matrix_op<font color='#5555FF'>&lt;</font>example_op_vector_to_matrix<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font> <b><a name='example_vector_to_matrix'></a>example_vector_to_matrix</b> <font face='Lucida Console'>(</font>
    <font color='#0000FF'>const</font> std::vector<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> vector
<font face='Lucida Console'>)</font>
<b>{</b>
    <font color='#0000FF'>typedef</font> example_op_vector_to_matrix<font color='#5555FF'>&lt;</font>T<font color='#5555FF'>&gt;</font> op;
    <font color='#0000FF'>return</font> matrix_op<font color='#5555FF'>&lt;</font>op<font color='#5555FF'>&gt;</font><font face='Lucida Console'>(</font><font color='#BB00BB'>op</font><font face='Lucida Console'>(</font>vector<font face='Lucida Console'>)</font><font face='Lucida Console'>)</font>;
<b>}</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> M, <font color='#0000FF'>typename</font> T<font color='#5555FF'>&gt;</font>
<font color='#0000FF'>struct</font> <b><a name='example_op_add_scalar'></a>example_op_add_scalar</b>
<b>{</b>
    <font color='#009900'>/*!
        This object defines a matrix expression that represents a matrix with a single
        scalar value added to all its elements.  
    !*/</font>

    <b><a name='example_op_add_scalar'></a>example_op_add_scalar</b><font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> M<font color='#5555FF'>&amp;</font> m_, <font color='#0000FF'>const</font> T<font color='#5555FF'>&amp;</font> val_<font face='Lucida Console'>)</font> : m<font face='Lucida Console'>(</font>m_<font face='Lucida Console'>)</font>, val<font face='Lucida Console'>(</font>val_<font face='Lucida Console'>)</font><b>{</b><b>}</b>

    <font color='#009900'>// A reference to the matrix 
</font>    <font color='#0000FF'>const</font> M<font color='#5555FF'>&amp;</font> m;
    <font color='#009900'>// A copy of the scalar value that should be added to each element of m
</font>    <font color='#0000FF'>const</font> T val;

    <font color='#009900'>// This time we add 1 to the cost since evaluating an element of this 
</font>    <font color='#009900'>// expression means performing 1 addition operation.
</font>    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> cost <font color='#5555FF'>=</font> M::cost <font color='#5555FF'>+</font> <font color='#979000'>1</font>;
    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NR <font color='#5555FF'>=</font> M::NR;
    <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> NC <font color='#5555FF'>=</font> M::NC;
    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::type type;
    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::mem_manager_type mem_manager_type;
    <font color='#0000FF'>typedef</font> <font color='#0000FF'>typename</font> M::layout_type layout_type;

    <font color='#009900'>// Note that we declare const_ret_type to be a non-reference type.  This is important
</font>    <font color='#009900'>// since apply() computes a new temporary value and thus we can't return a reference
</font>    <font color='#009900'>// to it.
</font>    <font color='#0000FF'>typedef</font> type const_ret_type; 
    const_ret_type <b><a name='apply'></a>apply</b> <font face='Lucida Console'>(</font><font color='#0000FF'><u>long</u></font> r, <font color='#0000FF'><u>long</u></font> c<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> <font color='#BB00BB'>m</font><font face='Lucida Console'>(</font>r,c<font face='Lucida Console'>)</font> <font color='#5555FF'>+</font> val; <b>}</b>

    <font color='#0000FF'><u>long</u></font> <b><a name='nr'></a>nr</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>nr</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#0000FF'><u>long</u></font> <b><a name='nc'></a>nc</b> <font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>nc</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>; <b>}</b>

    <font color='#009900'>// This expression aliases anything m aliases.
</font>    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='aliases'></a>aliases</b>               <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>aliases</font><font face='Lucida Console'>(</font>item<font face='Lucida Console'>)</font>; <b>}</b>
    <font color='#009900'>// Unlike the transpose expression.  This expression only destructively aliases something if m does. 
</font>    <font color='#009900'>// So this expression has the regular non-destructive kind of aliasing.
</font>    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font><font color='#0000FF'>typename</font> U<font color='#5555FF'>&gt;</font> <font color='#0000FF'><u>bool</u></font> <b><a name='destructively_aliases'></a>destructively_aliases</b> <font face='Lucida Console'>(</font> <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>U<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item<font face='Lucida Console'>)</font> <font color='#0000FF'>const</font> <b>{</b> <font color='#0000FF'>return</font> m.<font color='#BB00BB'>destructively_aliases</font><font face='Lucida Console'>(</font>item<font face='Lucida Console'>)</font>; <b>}</b>

<b>}</b>; 

<font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font> <font color='#0000FF'>typename</font> M, <font color='#0000FF'>typename</font> T <font color='#5555FF'>&gt;</font>
<font color='#0000FF'>const</font> matrix_op<font color='#5555FF'>&lt;</font>example_op_add_scalar<font color='#5555FF'>&lt;</font>M,T<font color='#5555FF'>&gt;</font> <font color='#5555FF'>&gt;</font> <b><a name='add_scalar'></a>add_scalar</b> <font face='Lucida Console'>(</font>
    <font color='#0000FF'>const</font> matrix_exp<font color='#5555FF'>&lt;</font>M<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> m,
    T val
<font face='Lucida Console'>)</font>
<b>{</b>
    <font color='#0000FF'>typedef</font> example_op_add_scalar<font color='#5555FF'>&lt;</font>M,T<font color='#5555FF'>&gt;</font> op;
    <font color='#0000FF'>return</font> matrix_op<font color='#5555FF'>&lt;</font>op<font color='#5555FF'>&gt;</font><font face='Lucida Console'>(</font><font color='#BB00BB'>op</font><font face='Lucida Console'>(</font>m.<font color='#BB00BB'>ref</font><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font>, val<font face='Lucida Console'>)</font><font face='Lucida Console'>)</font>;
<b>}</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<font color='#0000FF'><u>void</u></font> <b><a name='custom_matrix_expressions_example'></a>custom_matrix_expressions_example</b><font face='Lucida Console'>(</font>
<font face='Lucida Console'>)</font>
<b>{</b>
    matrix<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>double</u></font><font color='#5555FF'>&gt;</font> <font color='#BB00BB'>x</font><font face='Lucida Console'>(</font><font color='#979000'>2</font>,<font color='#979000'>3</font><font face='Lucida Console'>)</font>;
    x <font color='#5555FF'>=</font> <font color='#979000'>1</font>, <font color='#979000'>1</font>, <font color='#979000'>1</font>,
        <font color='#979000'>2</font>, <font color='#979000'>2</font>, <font color='#979000'>2</font>;

    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> x <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;

    <font color='#009900'>// Finally, lets use the matrix expressions we defined above.
</font>
    <font color='#009900'>// prints the transpose of x
</font>    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font color='#BB00BB'>example_trans</font><font face='Lucida Console'>(</font>x<font face='Lucida Console'>)</font> <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;

    <font color='#009900'>// prints this:
</font>    <font color='#009900'>//   11 11 11
</font>    <font color='#009900'>//   12 12 12
</font>    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font color='#BB00BB'>add_scalar</font><font face='Lucida Console'>(</font>x, <font color='#979000'>10</font><font face='Lucida Console'>)</font> <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;


    <font color='#009900'>// matrix expressions can be nested, even the user defined ones.
</font>    <font color='#009900'>// the following statement prints this:
</font>    <font color='#009900'>//   11 12 
</font>    <font color='#009900'>//   11 12 
</font>    <font color='#009900'>//   11 12 
</font>    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font color='#BB00BB'>example_trans</font><font face='Lucida Console'>(</font><font color='#BB00BB'>add_scalar</font><font face='Lucida Console'>(</font>x, <font color='#979000'>10</font><font face='Lucida Console'>)</font><font face='Lucida Console'>)</font> <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;

    <font color='#009900'>// Since we setup the alias detection correctly we can even do this:
</font>    x <font color='#5555FF'>=</font> <font color='#BB00BB'>example_trans</font><font face='Lucida Console'>(</font><font color='#BB00BB'>add_scalar</font><font face='Lucida Console'>(</font>x, <font color='#979000'>10</font><font face='Lucida Console'>)</font><font face='Lucida Console'>)</font>;
    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> "<font color='#CC0000'>new x:\n</font>" <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> x <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;

    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> "<font color='#CC0000'>Do some testing with the example_vector_to_matrix() function: </font>" <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;
    std::vector<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>float</u></font><font color='#5555FF'>&gt;</font> vect;
    vect.<font color='#BB00BB'>push_back</font><font face='Lucida Console'>(</font><font color='#979000'>1</font><font face='Lucida Console'>)</font>;
    vect.<font color='#BB00BB'>push_back</font><font face='Lucida Console'>(</font><font color='#979000'>3</font><font face='Lucida Console'>)</font>;
    vect.<font color='#BB00BB'>push_back</font><font face='Lucida Console'>(</font><font color='#979000'>5</font><font face='Lucida Console'>)</font>;

    <font color='#009900'>// Now lets treat our std::vector like a matrix and print some things.
</font>    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font color='#BB00BB'>example_vector_to_matrix</font><font face='Lucida Console'>(</font>vect<font face='Lucida Console'>)</font> <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;
    cout <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> <font color='#BB00BB'>add_scalar</font><font face='Lucida Console'>(</font><font color='#BB00BB'>example_vector_to_matrix</font><font face='Lucida Console'>(</font>vect<font face='Lucida Console'>)</font>, <font color='#979000'>10</font><font face='Lucida Console'>)</font> <font color='#5555FF'>&lt;</font><font color='#5555FF'>&lt;</font> endl;



    <font color='#009900'>/*
        As an aside, note that dlib contains functions equivalent to the ones we 
        defined above.  They are:
            - dlib::trans()
            - dlib::mat() (converts things into matrices)
            - operator+ (e.g. you can say my_mat + 1)


        Also, if you are going to be creating your own matrix expression you should also
        look through the matrix code in the dlib/matrix folder.  There you will find 
        many other examples of matrix expressions. 
    */</font>
<b>}</b>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>

</pre></body></html>