Represents a simple matrix class that keeps components in a column-major order. More...

#include <mexWoRB.h>

Public Member Functions
	Matrix (mwIndex rowCount, mwIndex columnCount)
	Creates an uninitialized matrix allocated using `mxAlloc`.
	Matrix (int nArgIn, const mxArray argIn[], int argNo, const char argDesc)
	Constructs the matrix from a `mexFunction` argument given by the argument number.
	Matrix (const char varName, const char workspace="caller")
	Constructs the matrix from MATLAB variable from the specified workspace.
	Matrix (const mxArray obj, mwIndex index, const char fieldName)
	Constructs the matrix from the given MATLAB structure field.
	~Matrix ()
	Destructor.
	operator mxArray * ()
	Converts an instance to a MATLAB double matrix (allocated on MATLAB heap)
bool	IsEmpty () const
	Returns true if the instance is an empty array.
bool	IsScalar () const
	Returns true if the instance is a scalar (1x1 matrix).
bool	IsVector () const
	Returns true if the instance is a vector (1xM or Nx1 matrix) or a scalar.
bool	IsRowVector () const
	Returns true if the instance is a row vector (1xM matrix).
bool	IsColumnVector () const
	Returns true if the instance is a column vector (Nx1 matrix).
bool	IsFullMatrix () const
	Returns true if the instance is non-empty matrix that is not a vector.
bool	IsSize (mwIndex M, mwIndex N) const
	Checks the sizes of each dimension of the matrix.
bool	IsValidRow (mwIndex r) const
	Returns true if the specified index points to a valid row.
bool	IsValidColumn (mwIndex c) const
	Returns true if the specified index points to a valid column.
mwIndex	Length () const
	Returns the length of the (linear) array of the matrix.
mwIndex	GetM () const
	Gets the number of rows in the matrix.
mwIndex	GetN () const
	Gets the number of columns in the matrix.
mwSize	MemorySize () const
	Gets the memory size (in bytes) occupied by array.
void	VerifyDims (mwIndex M, mwIndex N, const char *error_message) const
	Verifies sizes of each matrix dimension.
double &	operator() (mwIndex ix)
	Returns matrix element given by the linear index.
const double &	operator() (mwIndex ix) const
	Returns matrix element given by the linear index.
double &	operator() (mwIndex r, mwIndex c)
	Returns matrix element given by row and column index.
const double &	operator() (mwIndex r, mwIndex c) const
	Returns matrix element given by row and column index.
Private Member Functions
void	Initialize (const mxArray arg, const char argDesc)
	Initializes the matrix to refer to the given MATLAB array.
Private Attributes
mwIndex	NRows
	Holds the number of rows in matrix.
mwIndex	NCols
	Holds the number of columns in matrix.
double *	Data
	Holds the matrix data in column-major order.

Detailed Description

Represents a simple matrix class that keeps components in a column-major order.

Definition at line 20 of file mexWoRB.h.

Constructor & Destructor Documentation

Mex::Matrix::Matrix	(	mwIndex	rowCount,
		mwIndex	columnCount
	)		`[inline]`

Creates an uninitialized matrix allocated using mxAlloc.

Definition at line 65 of file mexWoRB.h.

References Data, and MemorySize().

            : NRows( rowCount )
            , NCols( columnCount )
            , Data( NULL )
        {
            Data = (double*)mxMalloc( MemorySize () ); 
        }

Mex::Matrix::Matrix	(	int	nArgIn,
		const mxArray *	argIn[],
		int	argNo,
		const char *	argDesc
	)		`[inline]`

Constructs the matrix from a mexFunction argument given by the argument number.

Definition at line 75 of file mexWoRB.h.

References Initialize().

            : NRows( 0 )
            , NCols( 0 )
            , Data( NULL )
        {
            if ( argNo < nArgIn ) {
                Initialize( argIn[ argNo ], argDesc );
            }
        }

Mex::Matrix::Matrix	(	const char *	varName,
		const char *	workspace = `"caller"`
	)		`[inline]`

Constructs the matrix from MATLAB variable from the specified workspace.

Definition at line 87 of file mexWoRB.h.

References Initialize().

        {
            Initialize( mexGetVariable( workspace, varName ), varName );
        }

Mex::Matrix::Matrix	(	const mxArray *	obj,
		mwIndex	index,
		const char *	fieldName
	)		`[inline]`

Constructs the matrix from the given MATLAB structure field.

Definition at line 94 of file mexWoRB.h.

References Initialize().

        {
            Initialize( mxGetField( obj, index, fieldName ), fieldName );
        }

Mex::Matrix::~Matrix ( ) [inline]

Destructor.

Does nothing. MATLAB automatically frees all data allocated by mxMalloc.

Definition at line 102 of file mexWoRB.h.

        {
        }

Member Function Documentation

mwIndex Mex::Matrix::GetM ( ) const [inline]

Gets the number of rows in the matrix.

Definition at line 200 of file mexWoRB.h.

References NRows.

Referenced by WoRB_MexFunction::CreateResultMatrix().

        {
            return NRows;
        }

mwIndex Mex::Matrix::GetN ( ) const [inline]

Gets the number of columns in the matrix.

Definition at line 207 of file mexWoRB.h.

References NCols.

Referenced by WoRB_MexFunction::CreateResultMatrix().

        {
            return NCols;
        }

void Mex::Matrix::Initialize	(	const mxArray *	arg,
		const char *	argDesc
	)		`[inline, private]`

Initializes the matrix to refer to the given MATLAB array.

This method does not copy data from the given MATLAB array.

Definition at line 37 of file mexWoRB.h.

References Data, NCols, NRows, and WoRB::SevereError().

Referenced by Matrix().

        {
            if ( arg == NULL ) {
                return;
            }

            // We expect a scalar, vector or a matrix of real numbers.
            //
            int ndim = mxGetNumberOfDimensions( arg );
            if ( ! mxIsDouble( arg ) || mxIsComplex( arg ) || ndim > 2 )
            {
                WoRB::SevereError( "WoRB:invarg",
                    "'%s' must be a scalar, vector or a matrix of real numbers.", 
                    argDesc
                );
            }

            // Get the matrix dimensions and the first element of the real data
            const mwSize* dims = mxGetDimensions( arg );
            NRows = ndim >= 1 ? dims[0] : 1;
            NCols = ndim >= 2 ? dims[1] : 1;
            Data  = mxGetPr( arg );
        }

bool Mex::Matrix::IsColumnVector ( ) const [inline]

Returns true if the instance is a column vector (Nx1 matrix).

Definition at line 158 of file mexWoRB.h.

References NCols, and NRows.

        {
            return NCols == 1 && NRows > 0;
        }

bool Mex::Matrix::IsEmpty ( ) const [inline]

Returns true if the instance is an empty array.

Definition at line 130 of file mexWoRB.h.

References NCols, and NRows.

Referenced by WoRB_MexFunction::OnProcessData().

        {
            return NRows * NCols == 0;
        }

bool Mex::Matrix::IsFullMatrix ( ) const [inline]

Returns true if the instance is non-empty matrix that is not a vector.

Definition at line 165 of file mexWoRB.h.

References NCols, and NRows.

        {
            return NCols > 1 && NRows > 1;
        }

bool Mex::Matrix::IsRowVector ( ) const [inline]

Returns true if the instance is a row vector (1xM matrix).

Definition at line 151 of file mexWoRB.h.

References NCols, and NRows.

        {
            return NRows == 1 && NCols > 0;
        }

bool Mex::Matrix::IsScalar ( ) const [inline]

Returns true if the instance is a scalar (1x1 matrix).

Definition at line 137 of file mexWoRB.h.

References NCols, and NRows.

        {
            return NRows == 1 && NCols == 1;
        }

bool Mex::Matrix::IsSize	(	mwIndex	M,
		mwIndex	N
	)		const `[inline]`

Checks the sizes of each dimension of the matrix.

Definition at line 172 of file mexWoRB.h.

References NCols, and NRows.

Referenced by WoRB_MexFunction::Parse(), and VerifyDims().

        {
            return M == NRows && N == NCols;
        }

bool Mex::Matrix::IsValidColumn ( mwIndex c ) const [inline]

Returns true if the specified index points to a valid column.

Definition at line 186 of file mexWoRB.h.

References NCols.

        {
            return 0 <= c && c < NCols;
        }

bool Mex::Matrix::IsValidRow ( mwIndex r ) const [inline]

Returns true if the specified index points to a valid row.

Definition at line 179 of file mexWoRB.h.

References NRows.

        {
            return 0 <= r && r < NRows;
        }

bool Mex::Matrix::IsVector ( ) const [inline]

Returns true if the instance is a vector (1xM or Nx1 matrix) or a scalar.

Definition at line 144 of file mexWoRB.h.

References NCols, and NRows.

        {
            return ( NRows == 1 && NCols > 0 ) || ( NCols == 1 && NRows > 0 );
        }

mwIndex Mex::Matrix::Length ( ) const [inline]

Returns the length of the (linear) array of the matrix.

Definition at line 193 of file mexWoRB.h.

References NCols, and NRows.

Referenced by operator()(), and VerifyDims().

        {
            return NRows * NCols;
        }

mwSize Mex::Matrix::MemorySize ( ) const [inline]

Gets the memory size (in bytes) occupied by array.

Definition at line 214 of file mexWoRB.h.

References NCols, and NRows.

Referenced by Matrix().

        {
            return NRows * NCols * sizeof( double );
        }

Mex::Matrix::operator mxArray * ( ) [inline]

Converts an instance to a MATLAB double matrix (allocated on MATLAB heap)

Definition at line 108 of file mexWoRB.h.

References Data, NCols, and NRows.

        {
            // Note: The array creation with mxCreateDoubleMatrix initializes
            // the array memory by filling it with zeros. The following code avoids
            // this unnecessary initialization.

            // Create an uninitialized empty array
            mxArray* result = mxCreateDoubleMatrix( 0, 0, mxREAL );
        
            // Set dimensions (note that either of NRows/NCols may be 0)
            mxSetM( result, NRows );  // Set M = row count
            mxSetN( result, NCols );  // Set N = column count

            if ( NRows && NCols ) {
                mxSetData( result, Data ); // Set mxArray data to point to output
            }

            return result;
        }

double& Mex::Matrix::operator() ( mwIndex ix ) [inline]

Returns matrix element given by the linear index.

Definition at line 239 of file mexWoRB.h.

References Data, Length(), NCols, NRows, and WoRB::SevereError().

        {
            if ( ix < 0 || ix >= Length () ) {
                WoRB::SevereError( 
                    "Matrix:elem:invdim",
                    "Linear index %d outside dimensions [ %d × %d ]", ix, NRows, NCols
                ); 
            }

            return Data[ ix ];
        }

const double& Mex::Matrix::operator() ( mwIndex ix ) const [inline]

Returns matrix element given by the linear index.

Definition at line 253 of file mexWoRB.h.

References Data, Length(), NCols, NRows, and WoRB::SevereError().

        {
            if ( ix < 0 || ix >= Length () ) {
                WoRB::SevereError( 
                    "Matrix:elem:invdim",
                    "Linear index %d outside dimensions [ %d × %d ]", ix, NRows, NCols
                ); 
            }

            return Data[ ix ];
        }

double& Mex::Matrix::operator()	(	mwIndex	r,
		mwIndex	c
	)		`[inline]`

Returns matrix element given by row and column index.

Definition at line 267 of file mexWoRB.h.

References Data, Length(), NCols, NRows, and WoRB::SevereError().

        {
            mwIndex ix = r + c * NRows;
            if ( ix < 0 || ix >= Length () ) {
                WoRB::SevereError( 
                    "Matrix:elem:invdim",
                    "Index (%d,%d) outside dimensions [ %d × %d ]", r, c, NRows, NCols
                ); 
            }

            return Data[ ix ];
        }

const double& Mex::Matrix::operator()	(	mwIndex	r,
		mwIndex	c
	)		const `[inline]`

Returns matrix element given by row and column index.

Definition at line 282 of file mexWoRB.h.

References Data, Length(), NCols, NRows, and WoRB::SevereError().

        {
            mwIndex ix = r + c * NRows;
            if ( ix < 0 || ix >= Length () ) {
                WoRB::SevereError( 
                    "Matrix:elem:invdim",
                    "Index (%d,%d) outside dimensions [ %d × %d ]", r, c, NRows, NCols
                ); 
            }

            return Data[ ix ];
        }

void Mex::Matrix::VerifyDims	(	mwIndex	M,
		mwIndex	N,
		const char *	error_message
	)		const `[inline]`

Verifies sizes of each matrix dimension.

Reports severe error if dimensions do not agree.

Definition at line 222 of file mexWoRB.h.

References IsSize(), Length(), NCols, NRows, and WoRB::SevereError().

Referenced by WoRB_MexFunction::Parse().

        {
            if ( IsSize( M, N ) || ( Length () == 0 && M * N == 0 ) ) {
                return; // OK
            }

            WoRB::SevereError( 
                "Matrix:VerifyDims:invsize",
                "%s; Required dimensions [ %d × %d ] have only [ %d × %d ]", 
                error_message, M, N, NRows, NCols
            ); 
        }