<sect1> <title>EST_TMatrix </title> <para> The EST_TMatrix class is a generl purpose 2 dimensional array container class. It handles memory allocation and (if required) bounds checking and is reasonably efficiant, so there should be little need to use bare &cpp; arays. </para> <formalpara> <title>See also</title><para> <itemizedlist> <listitem><para>EST_TMatrix</para></listitem> <listitem><para>EST_TVector</para></listitem> </itemizedlist> </para></formalpara> <programlisting arch='c'>#include "EST_TMatrix.h" #include "EST_String.h" </programlisting> <sect2> <title>Basic Matrix Use</title> <para> Instances of the TMatrix class are intended to behave as you would expect two dimensional arrays to work. </para> <simplesect> <title>Declaration</title> <para> Matrixes are declared by giving the type and the number of rows and columns. Here we create a 10 row by 5 column matrix. </para> </simplesect> <programlisting arch='c'> EST_TMatrix<float> m(10, 5); </programlisting> <simplesect> <title>Access</title> <para> Access to values in the matrix is via the a() member function. This returns a reference, so you can assign values to matrix cells. As is usually the case in &cpp;, column and row indecies start from 0. </para> </simplesect> <programlisting arch='c'> for(int i=0; i<m.num_rows(); i++) for(int j=0; j<m.num_columns(); j++) m.a(i,j) = i+j/100.0; // <lineannotation>Just something easy to recognise</lineannotation> </programlisting> <simplesect> <title>Output</title> <para> A simple output method is supplied, it just outputs a row at a time, tab separated to a named file. A filename of "-" means standard output. </para> </simplesect> <programlisting arch='c'> cout << "Initial Matrix\n"; m.save("-"); cout << "\n"; </programlisting> <simplesect> <title>Resizing</title> <para> Resize to 20 rows by 10 columns This fills the new area with <parameter>def_val</parameter>, which is 0.0 for floats. </para> </simplesect> <programlisting arch='c'> m.resize(20,10); </programlisting> </sect2> <sect2> <title>Copying Data to/from a buffer</title> <para> Whole rows or columns can be extracted into a buffer, or can be filled with data from a buffer. The buffer must be pre-declared, and it is up to you to ensure it is big enough. </para> <para> Data can be extracted into a buffer in one operation </para> <programlisting arch='c'> float *buf = new float[max(m.num_rows(),m.num_columns())]; m.copy_row(5, buf); </programlisting> <para> And data can be inserted in a similar manner. </para> <programlisting arch='c'> m.set_column(5,buf); </programlisting> </sect2> <sect2> <title>Sub-Matrices and Sub-Vectors</title> <para> A sub-vector or sub-matrix is a window onto a matrix. If you obtain a sub vector representing a row, for instance, you can treat it a normal vector, any changes you make affecting the underlying matrix. </para> <para> Here is how we can create new variables which refer to the 11th row, 4th column and a 5X3 rectnagle with top left hand corner (8,2). (since the first column or row is numbered 0, the numbers may be one less than you expect). </para> <programlisting arch='c'> EST_TVector<float> row; EST_TVector<float> column; EST_TMatrix<float> rectangle; m.row(row, 10); m.column(column, 3); m.sub_matrix(rectangle, 8, 5, 2, 3); </programlisting> <para> If we update the sub-vector, the main matrix changes. </para> <programlisting arch='c'> // <lineannotation>10th row becomes squares of the index</lineannotation> for(int i2=0; i2<row.n(); i2++) row[i2] = i2*i2; // <lineannotation>3rd column becomes cubes of the index</lineannotation> for(int i3=0; i3<column.n(); i3++) column[i3] = i3*i3*i3; // <lineannotation>Central rectangle filled with -1</lineannotation> for(int i4=0; i4<rectangle.num_rows(); i4++) for(int j4=0; j4<rectangle.num_columns(); j4++) rectangle.a(i4, j4) = -1; </programlisting> <para> We can even extract rows and columns from a sub-matrix as follows. </para> <programlisting arch='c'> EST_TVector<float> rrow; EST_TVector<float> rcolumn; // <lineannotation>3rd row of sub-matrix, part of 12th row of main matrix</lineannotation> rectangle.row(rrow, 2); // <lineannotation>2nd column of sub-matrix, part of 8th column of main matrix</lineannotation> rectangle.column(rcolumn, 1); </programlisting> </sect2> <sect2> <title>Template Instantiation.</title> <para> Some &cpp; compilers requre explicit guidance about which types of Matrix will be used. For many common types, including float, this guidance is included in the &est; libraries. However, if you need to use matrecies of your own types, you will need to include declarations similar to the following. </para> <programlisting arch='c'>Declare_TMatrix(MyType) #if defined(INSTANTIATE_TEMPLATES) #include "../base_class/EST_TMatrix.cc" Instantiate_TMatrix(MyType) #endif </programlisting> <para> By using this form of declaration, you should ensure that your code will compile anywhere where the speech tools libraries will. </para> </sect2> </sect1>