Main Content

mwArray

Class used to pass input/output arguments to C++ functions generated by MATLAB Compiler SDK

Description

Use the mwArray class to pass input/output arguments to generated C++ interface functions. This class consists of a thin wrapper around a MATLAB® array. All data in MATLAB is represented by arrays. The mwArray class provides the necessary constructors, methods, and operators for array creation and initialization, as well as simple indexing.

Note

Arithmetic operators, such as addition and subtraction, are no longer supported as of Release 14.

Required Headers

  • mclcppclass.h

  • mclmcrrt.h

Tip

MATLAB Compiler SDK™ automatically includes these header files in the header file generated for your MATLAB functions.

Constructors

mwArray()

Description

Construct empty array of type mxDOUBLE_CLASS.

mwArray(mxClassID mxID)

Description

Construct empty array of specified type.

Arguments
mxClassID mxIDValid mxClassID specifying the type of array to construct. See Work with mxArrays for more information on mxClassID.

mwArray(mwSize num_rows, mwSize num_cols, mxClassID mxID, mxComplexity cmplx = mxREAL)

Description

Create a 2–D matrix of the specified type and complexity. For nonnumeric types, mxComplexity will be ignored. For numeric types, pass mxCOMPLEX for the last argument to create a complex matrix; otherwise, the matrix will be real. All elements are initialized to zero. For cell matrices, all elements are initialized to empty cells.

Arguments
mwSize num_rowsNumber of rows in the array
mwSize num_colsNumber of columns in the array
mxClassID mxIDValid mxClassID specifying the type of array to construct. See Work with mxArrays for more information on mxClassID.
mxComplexity cmplxComplexity of the array to create. Valid values are mxREAL and mxCOMPLEX. The default value is mxREAL.

mwArray(mwSize num_dims, const mwSize* dims, mxClassID mxID, mxComplexity cmplx = mxREAL)

Description

Create an n-dimensional array of the specified type and complexity. For nonnumeric types, mxComplexity will be ignored. For numeric types, pass mxCOMPLEX for the last argument to create a complex matrix; otherwise, the array will be real. All elements are initialized to zero. For cell arrays, all elements are initialized to empty cells.

Arguments
mwSize num_dimsNumber of dimensions in the array
const mwSize* dimsDimensions of the array
mxClassID mxIDValid mxClassID specifying the type of array to construct. See Work with mxArrays for more information on mxClassID.
mxComplexity cmplxComplexity of the array to create. Valid values are mxREAL and mxCOMPLEX. The default value is mxREAL.

mwArray(const char* str)

Description

Create a 1-by-n array of type mxCHAR_CLASS, with n = strlen(str), and initialize the array's data with the characters in the supplied string.

Arguments
const char* strNull-terminated character buffer used to initialize the array

mwArray(mwSize num_strings, const char** str)

Description

Create a matrix of type mxCHAR_CLASS, and initialize the array's data with the characters in the supplied strings. The created array has dimensions m-by-max, where m is the number of strings and max is the length of the longest string in str.

Arguments
mwSize num_stringsNumber of strings in the input array
const char** strArray of null-terminated strings

mwArray(mwSize num_rows, mwSize num_cols, int num_fields, const char** fieldnames)

Description

Create a matrix of type mxSTRUCT_CLASS, with the specified field names. All elements are initialized with empty cells.

Arguments
mwSize num_rowsNumber of rows in the array
mwSize num_colsNumber of columns in the array
int num_fieldsNumber of fields in the struct matrix.
const char** fieldnamesArray of null-terminated strings representing the field names

mwArray(mwSize num_dims, const mwSize* dims, int num_fields, const char** fieldnames)

Description

Create an n-dimensional array of type mxSTRUCT_CLASS, with the specified field names. All elements are initialized with empty cells.

Arguments
mwSize num_dimsNumber of dimensions in the array
const mwSize* dimsDimensions of the array
int num_fieldsNumber of fields in the struct matrix.
const char** fieldnamesArray of null-terminated strings representing the field names

mwArray(const mwArray& arr)

Description

Create a deep copy of an existing array.

Arguments
mwArray& arrmwArray to copy

mwArray(<type> re)

Description

Create a real scalar array.

The scalar array is created with the type of the input argument.

Arguments
<type> reScalar value to initialize the array. <type> can be any of the following:
  • mxDouble

  • mxSingle

  • mxInt8

  • mxUint8

  • mxInt16

  • mxUint16

  • mxInt32

  • mxUint32

  • mxInt64

  • mxUint64

  • mxLogical

mwArray(<type> re, <type> im)

Description

Create a complex scalar array.

The scalar array is created with the type of the input argument.

Arguments
<type> reScalar value to initialize the real part of the array
<type> imScalar value to initialize the imaginary part of the array

<type> can be any of the following:

  • mxDouble

  • mxSingle

  • mxInt8

  • mxUint8

  • mxInt16

  • mxUint16

  • mxInt32

  • mxUint32

  • mxInt64

  • mxUint64

  • mxLogical

Methods

mwArray Clone() const

Description

Create a new array representing deep copy of array.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mwArray b = a.Clone();

mwArray SharedCopy() const

Description

Create a shared copy of an existing array. The new array and the original array both point to the same data.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mwArray b = a.SharedCopy();

mwArray Serialize() const

Description

Serialize an array into bytes. A 1-by-n numeric matrix of type mxUINT8_CLASS is returned containing the serialized data. The data can be deserialized back into the original representation by calling mwArray::Deserialize().

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mwArray b = a.Serialize();

mxClassID ClassID() const

Description

Determine the type of the array. See Work with mxArrays for more information on mxClassID.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mxClassID id = a.ClassID();

size_t ElementSize() const

Description

Determine the size, in bytes, of an element of array type. If the array is complex, the return value will represent the size, in bytes, of the real part of an element.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
int size = a.ElementSize();

mwSize NumberOfElements() const

Description

Determine the total size of the array.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
int n = a.NumberOfElements();

mwSize NumberOfNonZeros() const

Description

Determine the size of the array's data. If the underlying array is not sparse, this returns the same value as NumberOfElements().

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
int n = a.NumberOfNonZeros();

mwSize MaximumNonZeros() const

Description

Determine the allocated size of the array's data. If the underlying array is not sparse, this returns the same value as NumberOfElements().

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
int n = a.MaximumNonZeros();

mwSize NumberOfDimensions() const

Description

Determine the dimensionality of the array.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
int n = a.NumberOfDimensions();

int NumberOfFields() const

Description

Determine the number of fields in a struct array. If the underlying array is not of type struct, zero is returned.

Example
const char* fields[] = {"a", "b", "c"};
mwArray a(2, 2, 3, fields);
int n = a.NumberOfFields();

mwString GetFieldName(int index)

Description

Determine the name of a given field in a struct array. If the underlying array is not of type struct, an exception is thrown.

Arguments
int indexIndex of the field to name. Indexing starts at zero.
Example
const char* fields[] = {"a", "b", "c"};
mwArray a(2, 2, 3, fields);
mwString tempname = a.GetFieldName(1);
const char* name = (const char*)tempname;

mwArray GetDimensions() const

Description

Determine the size of each dimension in the array. The size of the returned array is 1-by-NumberOfDimensions().

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mwArray dims = a.GetDimensions();

bool IsEmpty() const

Description

Determine if an array is empty.

Example
mwArray a;
bool b = a.IsEmpty();

bool IsSparse() const

Description

Determine if an array is sparse.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
bool b = a.IsSparse();

bool IsNumeric() const

Description

Determine if an array is numeric.

Example
mwArray a(2, 2, mxDOUBLE_CLASS);
bool b = a.IsNumeric();

bool IsComplex() const

Description

Determine if an array is complex.

Example
mwArray a(2, 2, mxDOUBLE_CLASS, mxCOMPLEX);
bool b = a.IsComplex();

bool Equals(const mwArray& arr) const

Description

Returns true if the input array is byte-wise equal to this array. This method makes a byte-wise comparison of the underlying arrays. Therefore, arrays of the same type should be compared. Arrays of different types will not in general be equal, even if they are initialized with the same data.

Arguments
mwArray& arrArray to compare to array.
Example
mwArray a(1, 1, mxDOUBLE_CLASS);
mwArray b(1, 1, mxDOUBLE_CLASS);
a = 1.0;
b = 1.0;
bool c = a.Equals(b);

int CompareTo(const mwArray& arr) const

Description

Compares this array with the specified array for order. This method makes a byte-wise comparison of the underlying arrays. Therefore, arrays of the same type should be compared. Arrays of different types will, in general, not be ordered equivalently, even if they are initialized with the same data.

Arguments
mwArray& arrArray to compare to array.
Example
mwArray a(1, 1, mxDOUBLE_CLASS);
mwArray b(1, 1, mxDOUBLE_CLASS);
a = 1.0;
b = 1.0;
int n = a.CompareTo(b);

int HashCode() const

Description

Constructs a unique hash value from the underlying bytes in the array. Therefore, arrays of different types will have different hash codes, even if they are initialized with the same data.

Example
mwArray a(1, 1, mxDOUBLE_CLASS);
int n = a.HashCode();

mwString ToString() const

Description

Returns a string representation of the underlying array. The string returned is the same one that is returned by typing a variable's name at the MATLAB command prompt.

Example
mwArray a(1, 1, mxDOUBLE_CLASS, mxCOMPLEX);
a.Real() = 1.0;
a.Imag() = 2.0;
printf("%s\n", (const char*)(a.ToString()));

mwArray RowIndex() const

Description

Returns an array representing the row indices (first dimension) of the elements of this array in column-major order. For sparse arrays, the indices are returned for just the non-zero elements and the size of the array returned is 1-by-NumberOfNonZeros(). For nonsparse arrays, the size of the array returned is 1-by-NumberOfElements(), and the row indices of all of the elements are returned.

Example
#include <stdio.h>
mwArray a(1, 1, mxDOUBLE_CLASS);
mwArray rows = a.RowIndex();

mwArray ColumnIndex() const

Description

Returns an array representing the column indices (second dimension) of the elements of this array in column-major order. For sparse arrays, the indices are returned for just the non-zero elements and the size of the array returned is 1-by-NumberOfNonZeros(). For nonsparse arrays, the size of the array returned is 1-by-NumberOfElements(), and the column indices of all of the elements are returned.

Example
mwArray a(1, 1, mxDOUBLE_CLASS);
mwArray rows = a.ColumnIndex();

void MakeComplex()

Description

Convert a numeric array that has been previously allocated as real to complex. If the underlying array is of a nonnumeric type, an mwException is thrown.

Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
double idata[4] = {10.0, 20.0, 30.0, 40.0};
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(rdata, 4);
a.MakeComplex();
a.Imag().SetData(idata, 4);

mwArray Get(mwSize num_indices, ...)

Description

Fetches a single element at a specified index. The number of indices is passed, followed by a comma-separated list of 1-based indices. The valid number of indices that can be passed in is either 1 (single subscript indexing) or NumberOfDimensions() (multiple subscript indexing). In single subscript indexing the element at the specified 1-based offset is returned, accessing data in column-major order. In multiple subscript indexing the index list is used to access the specified element. The valid range for indices is 1 <= index <= NumberOfElements(), for single subscript indexing. For multiple subscript indexing, the ith index has the valid range: 1 <= index[i] <= GetDimensions().Get(1, i). An mwException is thrown if an invalid number of indices is passed in or if any index is out of bounds.

Arguments
mwSize num_indicesNumber of indices passed in
...Comma-separated list of input indices. Number of items must equal num_indices but should not exceed 32.
Example
double data[4] = {1.0, 2.0, 3.0, 4.0};
double x;
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(data, 4);
x = a.Get(1,1);
x = a.Get(2, 1, 2);
x = a.Get(2, 2, 2);

mwArray Get(const char* name, mwSize num_indices, ...)

Description

Fetches a single element at a specified field name and index. This method may only be called on an array that is of type mxSTRUCT_CLASS. An mwException is thrown if the underlying array is not a struct array. The field name passed must be a valid field name in the struct array. The index is passed by first passing the number of indices followed by a comma-separated list of 1-based indices. The valid number of indices that can be passed in is either 1 (single subscript indexing) or NumberOfDimensions() (multiple subscript indexing). In single subscript indexing the element at the specified 1-based offset is returned, accessing data in column-wise order. In multiple subscript indexing the index list is used to access the specified element. The valid range for indices is 1 <= index <= NumberOfElements(), for single subscript indexing. For multiple subscript indexing, the ith index has the valid range: 1 <= index[i] <= GetDimensions().Get(1, i). An mwException is thrown if an invalid number of indices is passed in or if any index is out of bounds.

Arguments
char* nameNull-terminated character buffer containing the name of the field
mwSize num_indicesNumber of indices passed in
...Comma-separated list of input indices. Number of items must equal num_indices but should not exceed 32.
Example
const char* fields[] = {"a", "b", "c"};

mwArray a(1, 1, 3, fields);
mwArray b = a.Get("a", 1, 1);
mwArray b = a.Get("b", 2, 1, 1);

mwArray Real()

Description

Accesses the real part of a complex array. The returned mwArray is considered real and has the same dimensionality and type as the original.

Complex arrays consist of Complex numbers, which are 1-by-2 vectors (pairs). For example, if the number is 3+5i, then the pair is (3,5i). An array of Complex numbers is therefore two dimensional (N-by-2), where N is the number of complex numbers in the array. 2+4i, 7-3i, 8+6i would be represented as (2,4i) (7,3i) (8,6i). Complex numbers have two components, real and imaginary.

Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
double idata[4] = {10.0, 20.0, 30.0, 40.0};
mwArray a(2, 2, mxDOUBLE_CLASS, mxCOMPLEX);
a.Real().SetData(rdata, 4);

mwArray Imag()

Description

Accesses the imaginary part of a complex array. The returned mwArray is considered real and has the same dimensionality and type as the original.

Complex arrays consist of Complex numbers, which are 1-by-2 vectors (pairs). For example, if the number is 3+5i, then the pair is (3,5i). An array of Complex numbers is therefore two dimensional (N-by-2), where N is the number of complex numbers in the array. 2+4i, 7-3i, 8+6i would be represented as (2,4i) (7,3i) (8,6i). Complex numbers have two components, real and imaginary.

Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
double idata[4] = {10.0, 20.0, 30.0, 40.0};
mwArray a(2, 2, mxDOUBLE_CLASS, mxCOMPLEX);
a.Imag().SetData(idata, 4);

void Set(const mwArray& arr)

Description

Assign shared copy of input array to currently referenced cell for arrays of type mxCELL_CLASS and mxSTRUCT_CLASS.

Arguments
mwArray& arrmwArray to assign to currently referenced cell
Example
mwArray a(2, 2, mxDOUBLE_CLASS);
mwArray b(2, 2, mxINT16_CLASS);
mwArray c(1, 2, mxCELL_CLASS);
c.Get(1,1).Set(a);
c.Get(1,2).Set(b);

void GetData(<numeric-type>* buffer, mwSize len) const

Description

Copies the array's data into supplied numeric buffer.

The data is copied in column-major order. If the underlying array is not of the same type as the input buffer, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

Arguments
<numeric-type>* bufferBuffer to receive copy. Valid types for <numeric-type> are:
  • mxDOUBLE_CLASS

  • mxSINGLE_CLASS

  • mxINT8_CLASS

  • mxUINT8_CLASS

  • mxINT16_CLASS

  • mxUINT16_CLASS

  • mxINT32_CLASS

  • mxUINT32_CLASS

  • mxINT64_CLASS

  • mxUINT64_CLASS

mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
double data_copy[4] ;
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(rdata, 4);
a.GetData(data_copy, 4);

void GetLogicalData(mxLogical* buffer, mwSize len) const

Description

Copies the array's data into supplied mxLogical buffer.

The data is copied in column-major order. If the underlying array is not of type mxLOGICAL_CLASS, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

Arguments
mxLogical* bufferBuffer to receive copy
mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
mxLogical data[4] = {true, false, true, false};
mxLogical data_copy[4] ;
mwArray a(2, 2, mxLOGICAL_CLASS);
a.SetLogicalData(data, 4);
a.GetLogicalData(data_copy, 4);

void GetCharData(mxChar* buffer, mwSize len) const

Description

Copies the array's data into supplied mxChar buffer.

The data is copied in column-major order. If the underlying array is not of type mxCHAR_CLASS, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

Arguments
mxChar** bufferBuffer to receive copy
mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
mxChar data[6] = {'H', 'e' , `l' , 'l' , 'o' , '\0'};
mxChar data_copy[6] ;
mwArray a(1, 6, mxCHAR_CLASS);
a.SetCharData(data, 6);
a.GetCharData(data_copy, 6);

void SetData(<numeric-type>* buffer, mwSize len)

Description

Copies the data from supplied numeric buffer into the array.

The data is copied in column-major order. If the underlying array is not of the same type as the input buffer, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

You cannot use SetData to dynamically resize an mwArray.

Arguments
<numeric-type>* bufferBuffer containing data to copy. Valid types for <numeric-type> are:
  • mxDOUBLE_CLASS

  • mxSINGLE_CLASS

  • mxINT8_CLASS

  • mxUINT8_CLASS

  • mxINT16_CLASS

  • mxUINT16_CLASS

  • mxINT32_CLASS

  • mxUINT32_CLASS

  • mxINT64_CLASS

  • mxUINT64_CLASS

mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
double data_copy[4] ;
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(rdata, 4);
a.GetData(data_copy, 4);

void SetLogicalData(mxLogical* buffer, mwSize len)

Description

Copies the data from the supplied mxLogical buffer into the array.

The data is copied in column-major order. If the underlying array is not of type mxLOGICAL_CLASS, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

Arguments
mxLogical* bufferBuffer containing data to copy
mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
mxLogical data[4] = {true, false, true, false};
mxLogical data_copy[4] ;
mwArray a(2, 2, mxLOGICAL_CLASS);
a.SetLogicalData(data, 4);
a.GetLogicalData(data_copy, 4);

void SetCharData(mxChar* buffer, mwSize len)

Description

Copies the data from the supplied mxChar buffer into the array.

The data is copied in column-major order. If the underlying array is not of type mxCHAR_CLASS, the data is converted to this type as it is copied. If a conversion cannot be made, an mwException is thrown.

Arguments
mxChar** bufferBuffer containing data to copy
mwSize lenMaximum length of buffer. A maximum of len elements will be copied.
Example
mxChar data[6] = {'H', 'e' , `l' , 'l' , 'o' , '\0'};
mxChar data_copy[6] ;
mwArray a(1, 6, mxCHAR_CLASS);
a.SetCharData(data, 6);
a.GetCharData(data_copy, 6);

static mwArray Deserialize(const mwArray& arr)

Description

Deserializes an array that has been serialized with mwArray::Serialize(). The input array must be of type mxUINT8_CLASS and contain the data from a serialized array. If the input data does not represent a serialized mwArray, the behavior of this method is undefined.

Arguments
mwArray& arrmwArray that has been obtained by calling mwArray::Serialize
Example
double rdata[4] = {1.0, 2.0, 3.0, 4.0};
mwArray a(1,4,mxDOUBLE_CLASS); 
a.SetData(rdata, 4);
mwArray b = a.Serialize();
a = mwArray::Deserialize(b);

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rdata, mwSize num_rows, mwSize num_cols, mwSize nzmax)

Description

Creates real sparse matrix of type double with specified number of rows and columns.

The lengths of input row, column index, and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated throughout the construction of the matrix.

If the same row/column pair occurs more than once, the data value assigned to that element is the sum of all values associated with that pair. If any element of the rowindex or colindex array is greater than the specified values in num_rows or num_cols respectively, an exception is thrown.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxDouble* rdataData associated with non-zero row and column indices
mwSize num_rowsNumber of rows in matrix
mwSize num_colsNumber of columns in matrix
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

This example constructs a sparse 4-by-4 tridiagonal matrix:

2 -1  0  0
-1  2 -1  0
0 -1  2 -1
0  0 -1  2

The following code, when run:

double rdata[]        = 
           {2.0, -1.0, -1.0, 2.0, -1.0, 
            -1.0, 2.0, -1.0, -1.0, 2.0};
mwIndex row_tridiag[] = 
           {1,    2,    1,   2,    3,
            2,   3,    4,    3,   4  };
mwIndex col_tridiag[] = 
           {1,    1,    2,   2,    2, 
              3,   3,    3,    4,   4  };

mwArray mysparse = 
           mwArray::NewSparse(10, row_tridiag, 
                              10, col_tridiag, 
                              10, rdata, 4, 4, 10);
std::cout << mysparse << std::endl;

will display the following output to the screen:

 (1,1)        2
 (2,1)       -1
 (1,2)       -1
 (2,2)        2
 (3,2)       -1
 (2,3)       -1
 (3,3)        2
 (4,3)       -1
 (3,4)       -1
 (4,4)        2

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rdata, mwSize nzmax)

Description

Creates real sparse matrix of type double with number of rows and columns inferred from input data.

The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

If the same row/column pair occurs more than once, the data value assigned to that element is the sum of all values associated with that pair. The number of rows and columns in the created matrix are calculated from the input rowindex and colindex arrays as num_rows = max{rowindex}, num_cols = max{colindex}.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxDouble* rdataData associated with non-zero row and column indices
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

In this example, we construct a sparse 4-by-4 identity matrix. The value of 1.0 is copied to each non-zero element defined by row and column index arrays:

double one = 1.0;
mwIndex row_diag[] = {1, 2, 3, 4};
mwIndex col_diag[] = {1, 2, 3, 4};

mwArray mysparse = 
  mwArray::NewSparse(4, row_diag, 
                     4, col_diag, 
                     1, &one, 
                     0);
std::cout << mysparse << std::endl;

(1,1)        1
(2,2)        1
(3,3)        1
(4,4)        1

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rdata, const mxDouble* idata, mwSize num_rows, mwSize num_cols, mwSize nzmax)

Description

Creates complex sparse matrix of type double with specified number of rows and columns.

The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

If the same row/column pair occurs more than once, the data value assigned to that element is the sum of all values associated with that pair. If any element of the rowindex or colindex array is greater than the specified values in num_rows, num_cols, respectively, then an exception is thrown.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxDouble* rdataReal part of data associated with non-zero row and column indices
mxDouble* idataImaginary part of data associated with non-zero row and column indices
mwSize num_rowsNumber of rows in matrix
mwSize num_colsNumber of columns in matrix
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

This example constructs a complex tridiagonal matrix:

double rdata[] = 
  {2.0, -1.0, -1.0, 2.0, -1.0, -1.0, 2.0, -1.0, -1.0, 2.0};
double idata[] = 
  {20.0, -10.0, -10.0, 20.0, -10.0, -10.0, 20.0, -10.0, 
                                              -10.0, 20.0};
mwIndex row_tridiag[] = 
  {1,    2,    1,   2,    3,    2,   3,    4,    3,   4};
mwIndex col_tridiag[] =
  {1,    1,    2,   2,    2,    3,   3,    3,    4,   4};

mwArray mysparse = mwArray::NewSparse(10, row_tridiag, 
                                      10, col_tridiag, 
                                      10, rdata, 
                                      idata, 4, 4, 10);
std::cout << mysparse << std::endl;

It displays the following output to the screen:

(1,1)      2.0000 +20.0000i
(2,1)     -1.0000 -10.0000i
(1,2)     -1.0000 -10.0000i
(2,2)      2.0000 +20.0000i
(3,2)     -1.0000 -10.0000i
(2,3)     -1.0000 -10.0000i
(3,3)      2.0000 +20.0000i
(4,3)     -1.0000 -10.0000i
(3,4)     -1.0000 -10.0000i
(4,4)      2.0000 +20.0000i

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxDouble* rdata, const mxDouble* idata, mwSize nzmax)

Description

Creates complex sparse matrix of type double with number of rows and columns inferred from input data.

The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

If the same row/column pair occurs more than once, the data value assigned to that element is the sum of all values associated with that pair. The number of rows and columns in the created matrix are calculated form the input rowindex and colindex arrays as num_rows = max{rowindex}, num_cols = max{colindex}.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxDouble* rdataReal part of data associated with non-zero row and column indices
mxDouble* idataImaginary part of data associated with non-zero row and column indices
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

This example constructs a complex matrix by inferring dimensions and storage allocation from the input data.

mwArray mysparse = 
   mwArray::NewSparse(10, row_tridiag, 
                      10, col_tridiag,
                      10, rdata, idata, 
                      0);
std::cout << mysparse << std::endl;

(1,1)      2.0000 +20.0000i
(2,1)     -1.0000 -10.0000i
(1,2)     -1.0000 -10.0000i
(2,2)      2.0000 +20.0000i
(3,2)     -1.0000 -10.0000i
(2,3)     -1.0000 -10.0000i
(3,3)      2.0000 +20.0000i
(4,3)     -1.0000 -10.0000i
(3,4)     -1.0000 -10.0000i
(4,4)      2.0000 +20.0000i

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxLogical* rdata, mwSize num_rows, mwSize num_cols, mwSize nzmax)

Description

Creates logical sparse matrix with specified number of rows and columns.

The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated throughout the construction of the matrix.

If the same row/column pair occurs more than once, the data value assigned to that element is the sum of all values associated with that pair. If any element of the rowindex or colindex array is greater than the specified values in num_rows, num_cols, respectively, then an exception is thrown.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxLogical* rdataData associated with non-zero row and column indices
mwSize num_rowsNumber of rows in matrix
mwSize num_colsNumber of columns in matrix
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

This example creates a sparse logical 4-by-4 tridiagonal matrix, assigning true to each non-zero value:

mxLogical one = true;
mwIndex row_tridiag[] = 
      {1,    2,    1,   2,    3,    
       2,   3,    4,    3,   4};
mwIndex col_tridiag[] = 
      {1,    1,    2,   2,    2,    
       3,   3,    3,    4,   4};

mwArray mysparse = 
      mwArray::NewSparse(10, row_tridiag,
                         10, col_tridiag, 
                          1, &one, 
                          4, 4, 10);
std::cout << mysparse << std::endl;

(1,1)        1
(2,1)        1
(1,2)        1
(2,2)        1
(3,2)        1
(2,3)        1
(3,3)        1
(4,3)        1
(3,4)        1
(4,4)        1

static mwArray NewSparse(mwSize rowindex_size, const mwIndex* rowindex, mwSize colindex_size, const mwIndex* colindex, mwSize data_size, const mxLogical* rdata, mwSize nzmax)

Description

Creates logical sparse matrix with number of rows and columns inferred from input data.

The lengths of input row and column index and data arrays must all be the same or equal to 1. In the case where any of these arrays are equal to 1, the value is repeated through out the construction of the matrix.

The number of rows and columns in the created matrix are calculated form the input rowindex and colindex arrays as num_rows = max {rowindex}, num_cols = max {colindex}.

Arguments
mwSize rowindex_sizeSize of rowindex array
mwIndex* rowindexArray of row indices of non-zero elements
mwSize colindex_sizeSize of colindex array
mwIndex* colindexArray of column indices of non-zero elements
mwSize data_sizeSize of data array
mxLogical* rdataData associated with non-zero row and column indices
mwSize nzmaxReserved storage for sparse matrix. If nzmax is zero, storage will be set to max{rowindex_size, colindex_size, data_size}.
Example

This example uses the data from the first example, but allows the number of rows, number of columns, and allocated storage to be calculated from the input data:

mwArray mysparse = 
    mwArray::NewSparse(10, row_tridiag, 
                       10, col_tridiag, 
                       1, &one, 
                       0);
std::cout << mysparse << std::endl;

(1,1)        1
(2,1)        1
(1,2)        1
(2,2)        1
(3,2)        1
(2,3)        1
(3,3)        1
(4,3)        1
(3,4)        1
(4,4)        1

static mwArray NewSparse (mwSize num_rows, mwSize num_cols, mwSize nzmax, mxClassID mxID, mxComplexity cmplx = mxREAL)

Description

Creates an empty sparse matrix. All elements in an empty sparse matrix are initially zero, and the amount of allocated storage for non-zero elements is specified by nzmax.

Arguments
mwSize num_rowsNumber of rows in matrix
mwSize num_colsNumber of columns in matrix
mwSize nzmaxReserved storage for sparse matrix
mxClassID mxIDType of data to store in matrix. Currently, sparse matrices of type double precision and logical are supported. Pass mxDOUBLE_CLASS to create a double precision sparse matrix. Pass mxLOGICAL_CLASS to create a logical sparse matrix.
mxComplexity cmplxComplexity of matrix. Pass mxCOMPLEX to create a complex sparse matrix and mxREAL to create a real sparse matrix. This argument may be omitted, in which case the default complexity is real
Example

This example constructs a real 3-by-3 empty sparse matrix of type double with reserved storage for 4 non-zero elements:

mwArray mysparse = mwArray::NewSparse
                (3, 3, 4, mxDOUBLE_CLASS);
std::cout << mysparse << std::endl;

All zero sparse: 3-by-3

static double GetNaN()

Description

Get value of NaN (Not-a-Number).

Call mwArray::GetNaN to return the value of NaN for your system. NaN is the IEEE arithmetic representation for Not-a-Number. Certain mathematical operations return NaN as a result, for example:

  • 0.0/0.0

  • Inf-Inf

The value of NaN is built in to the system; you cannot modify it.

Example
double x = mwArray::GetNaN();

static double GetEps()

Description

Returns the value of the MATLAB eps variable. This variable is the distance from 1.0 to the next largest floating-point number. Consequently, it is a measure of floating-point accuracy. The MATLAB pinv and rank functions use eps as a default tolerance.

Example
double x = mwArray::GetEps();

static double GetInf()

Description

Returns the value of the MATLAB internal Inf variable. Inf is a permanent variable representing IEEE arithmetic positive infinity. The value of Inf is built into the system; you cannot modify it.

Operations that return Inf include

  • Division by 0. For example, 5/0 returns Inf.

  • Operations resulting in overflow. For example, exp(10000) returns Inf because the result is too large to be represented on your machine.

Example
double x = mwArray::GetInf();

static bool IsFinite(double x)

Description

Determine whether or not a value is finite. A number is finite if it is greater than -Inf and less than Inf.

Arguments
double xValue to test for finiteness
Example
bool x = mwArray::IsFinite(1.0);

static bool IsInf(double x)

Description

Determines whether or not a value is equal to infinity or minus infinity. MATLAB stores the value of infinity in a permanent variable named Inf, which represents IEEE arithmetic positive infinity. The value of the variable, Inf, is built into the system; you cannot modify it.

Operations that return infinity include

  • Division by 0. For example, 5/0 returns infinity.

  • Operations resulting in overflow. For example, exp(10000) returns infinity because the result is too large to be represented on your machine. If the value equals NaN (Not-a-Number), then mxIsInf returns false. In other words, NaN is not equal to infinity.

Arguments
double xValue to test for infiniteness
Example
bool x = mwArray::IsInf(1.0);

static bool IsNaN(double x)

Description

Determines whether or not the value is NaN. NaN is the IEEE arithmetic representation for Not-a-Number. NaN is obtained as a result of mathematically undefined operations such as

  • 0.0/0.0

  • Inf-Inf

The system understands a family of bit patterns as representing NaN. In other words, NaN is not a single value, rather it is a family of numbers that the MATLAB software (and other IEEE-compliant applications) use to represent an error condition or missing data.

Arguments
double xValue to test for NaN
Example
bool x = mwArray::IsNaN(1.0);

Operators

mwArray operator()(mwIndex i1, mwIndex i2, mwIndex i3, ..., )

Description

Fetches a single element at a specified index. The index is passed as a comma-separated list of 1-based indices. This operator is overloaded to support 1 through 32 indices. The valid number of indices that can be passed in is either 1 (single subscript indexing) or NumberOfDimensions() (multiple subscript indexing). In single subscript indexing the element at the specified 1-based offset is returned, accessing data in column-wise order. In multiple subscript indexing the index list is used to access the specified element. The valid range for indices is 1 <= index <= NumberOfElements(), for single subscript indexing. For multiple subscript indexing, the ith index has the valid range: 1 <= index[i] <= GetDimensions().Get(1, i). An mwException is thrown if an invalid number of indices is passed in or if any index is out of bounds.

Arguments
mwIndex i1, mwIndex i2, mwIndex i3, ...,Comma-separated list of input indices
Example
double data[4] = {1.0, 2.0, 3.0, 4.0};
double x;
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(data, 4);
x = a(1,1);
x = a(1,2);
x = a(2,2);

mwArray operator()(const char* name, mwIndex i1, mwIndex i2, mwIndex i3, ..., )

Description

Fetches a single element at a specified field name and index. This method may only be called on an array that is of type mxSTRUCT_CLASS. An mwException is thrown if the underlying array is not a struct array. The field name passed must be a valid field name in the struct array. The index is passed by first passing the number of indices, followed by an array of 1-based indices. This operator is overloaded to support 1 through 32 indices. The valid number of indices that can be passed in is either 1 (single subscript indexing) or NumberOfDimensions() (multiple subscript indexing). In single subscript indexing the element at the specified 1-based offset is returned, accessing data in column-wise order. In multiple subscript indexing the index list is used to access the specified element. The valid range for indices is 1 <= index <= NumberOfElements(), for single subscript indexing. For multiple subscript indexing, the ith index has the valid range: 1 <= index[i] <= GetDimensions().Get(1, i). An mwException is thrown if an invalid number of indices is passed in or if any index is out of bounds.

Arguments
char* nameNull terminated string containing the field name to get
mwIndex i1, mwIndex i2, mwIndex i3, ...,Comma-separated list of input indices
Example
const char* fields[] = {"a", "b", "c"};
int index[2] = {1, 1};
mwArray a(1, 1, 3, fields);
mwArray b = a("a", 1, 1);
mwArray b = a("b", 1, 1);

mwArray& operator=(const <type>& x)

Description

Sets a single scalar value. This operator is overloaded for all numeric and logical types.

Arguments
const <type>& xValue to assign
Example
mwArray a(2, 2, mxDOUBLE_CLASS);
a(1,1) = 1.0;
a(1,2) = 2.0;
a(2,1) = 3.0;
a(2,2) = 4.0;

const mwArray operator()(mwIndex i1, mwIndex i2, mwIndex i3, ..., ) const

Description

Fetches a single scalar value. This operator is overloaded for all numeric and logical types.

Arguments
mwIndex i1, mwIndex i2, mwIndex i3, ...,Comma-separated list of input indices
Example
double data[4] = {1.0, 2.0, 3.0, 4.0};
double x;
mwArray a(2, 2, mxDOUBLE_CLASS);
a.SetData(data, 4);
x = (double)a(1,1);
x = (double)a(1,2);
x = (double)a(2,1);
x = (double)a(2,2);

std::ostream::operator<<(const mwArray &)

Description

Write mwArray to output stream. The output has the same format as the output when a variable's name is typed at the MATLAB command prompt. See ToString().

Version History

Introduced in R2013b