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.hmclmcrrt.h
Tip
MATLAB Compiler SDK™ automatically includes these header files in the header file generated for your MATLAB functions.
Constructors
mwArray()
Construct empty array of type mxDOUBLE_CLASS.
mwArray(mxClassID mxID)
Construct empty array of specified type.
mxClassID mxID | Valid 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)
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.
mwSize num_rows | Number of rows in the array |
mwSize num_cols | Number of columns in the array |
mxClassID mxID | Valid mxClassID specifying the type of array
to construct. See Work with mxArrays for more information on mxClassID. |
mxComplexity cmplx | Complexity 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)
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.
mwSize num_dims | Number of dimensions in the array |
const mwSize* dims | Dimensions of the array |
mxClassID mxID | Valid mxClassID specifying the type of array
to construct. See Work with mxArrays for more information on mxClassID. |
mxComplexity cmplx | Complexity of the array to create. Valid values are mxREAL and mxCOMPLEX.
The default value is mxREAL. |
mwArray(const char* str)
Create a 1-by-nmxCHAR_CLASS, with n = strlen(str),
and initialize the array's data with the characters in the supplied
string.
const char* str | Null-terminated character buffer used to initialize the array |
mwArray(mwSize num_strings, const char** str)
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.
mwSize num_strings | Number of strings in the input array |
const char** str | Array of null-terminated strings |
mwArray(mwSize num_rows, mwSize num_cols, int num_fields, const char** fieldnames)
Create a matrix of type mxSTRUCT_CLASS, with
the specified field names. All elements are initialized with empty
cells.
mwSize num_rows | Number of rows in the array |
mwSize num_cols | Number of columns in the array |
int num_fields | Number of fields in the struct matrix. |
const char** fieldnames | Array of null-terminated strings representing the field names |
mwArray(mwSize num_dims, const mwSize* dims, int num_fields, const char** fieldnames)
Create an n-dimensional array of type mxSTRUCT_CLASS,
with the specified field names. All elements are initialized with
empty cells.
mwSize num_dims | Number of dimensions in the array |
const mwSize* dims | Dimensions of the array |
int num_fields | Number of fields in the struct matrix. |
const char** fieldnames | Array of null-terminated strings representing the field names |
mwArray(const mwArray& arr)
Create a deep copy of an existing array.
mwArray& arr | mwArray to copy |
mwArray(<type> re)
Create a real scalar array.
The scalar array is created with the type of the input argument.
<type> re | Scalar value to initialize the array. <type> can
be any of the following:
|
mwArray(<type> re, <type> im)
Create a complex scalar array.
The scalar array is created with the type of the input argument.
<type> re | Scalar value to initialize the real part of the array |
<type> im | Scalar value to initialize the imaginary part of the array |
<type> can be any of the following:
mxDoublemxSinglemxInt8mxUint8mxInt16mxUint16mxInt32mxUint32mxInt64mxUint64mxLogical
Methods
mwArray Clone() const
Create a new array representing deep copy of array.
mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b = a.Clone();
mwArray SharedCopy() const
Create a shared copy of an existing array. The new array and the original array both point to the same data.
mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b = a.SharedCopy();
mwArray Serialize() const
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().
mwArray a(2, 2, mxDOUBLE_CLASS); mwArray b = a.Serialize();
mxClassID ClassID() const
Determine the type of the array. See Work with mxArrays for
more information on mxClassID.
mwArray a(2, 2, mxDOUBLE_CLASS); mxClassID id = a.ClassID();
size_t ElementSize() const
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.
mwArray a(2, 2, mxDOUBLE_CLASS); int size = a.ElementSize();
mwSize NumberOfElements() const
Determine the total size of the array.
mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfElements();
mwSize NumberOfNonZeros() const
Determine the size of the array's data. If the underlying array
is not sparse, this returns the same value as NumberOfElements().
mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfNonZeros();
mwSize MaximumNonZeros() const
Determine the allocated size of the array's data. If the underlying
array is not sparse, this returns the same value as NumberOfElements().
mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.MaximumNonZeros();
mwSize NumberOfDimensions() const
Determine the dimensionality of the array.
mwArray a(2, 2, mxDOUBLE_CLASS); int n = a.NumberOfDimensions();
int NumberOfFields() const
Determine the number of fields in a struct array.
If the underlying array is not of type struct,
zero is returned.
const char* fields[] = {"a", "b", "c"};
mwArray a(2, 2, 3, fields);
int n = a.NumberOfFields();mwString GetFieldName(int index)
Determine the name of a given field in a struct array.
If the underlying array is not of type struct,
an exception is thrown.
int index | Index of the field to name. Indexing starts at zero. |
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
Determine the size of each dimension in the array. The size
of the returned array is 1-by-NumberOfDimensions().
mwArray a(2, 2, mxDOUBLE_CLASS); mwArray dims = a.GetDimensions();
bool IsEmpty() const
Determine if an array is empty.
mwArray a; bool b = a.IsEmpty();
bool IsSparse() const
Determine if an array is sparse.
mwArray a(2, 2, mxDOUBLE_CLASS); bool b = a.IsSparse();
bool IsNumeric() const
Determine if an array is numeric.
mwArray a(2, 2, mxDOUBLE_CLASS); bool b = a.IsNumeric();
bool IsComplex() const
Determine if an array is complex.
mwArray a(2, 2, mxDOUBLE_CLASS, mxCOMPLEX); bool b = a.IsComplex();
bool Equals(const mwArray& arr) const
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.
mwArray& arr | Array to compare to array. |
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
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.
mwArray& arr | Array to compare to array. |
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
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.
mwArray a(1, 1, mxDOUBLE_CLASS); int n = a.HashCode();
mwString ToString() const
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.
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
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.
#include <stdio.h> mwArray a(1, 1, mxDOUBLE_CLASS); mwArray rows = a.RowIndex();
mwArray ColumnIndex() const
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.
mwArray a(1, 1, mxDOUBLE_CLASS); mwArray rows = a.ColumnIndex();
void MakeComplex()
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.
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, ...)
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 i1 <= 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.
mwSize num_indices | Number of indices passed in |
... | Comma-separated list of input indices. Number of items must
equal num_indices but should not exceed 32. |
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, ...)
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.
char* name | Null-terminated character buffer containing the name of the field |
mwSize num_indices | Number of indices passed in |
... | Comma-separated list of input indices. Number of items must
equal num_indices but should not exceed 32. |
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()
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.
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()
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.
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)
Assign shared copy of input array to currently referenced cell
for arrays of type mxCELL_CLASS and mxSTRUCT_CLASS.
mwArray& arr | mwArray to assign to currently referenced
cell |
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
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.
<numeric-type>* buffer | Buffer to receive copy. Valid types for <numeric-type> are:
|
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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
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.
mxLogical* buffer | Buffer to receive copy |
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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
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.
mxChar** buffer | Buffer to receive copy |
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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)
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.
<numeric-type>* buffer | Buffer containing data to copy. Valid types for <numeric-type> are:
|
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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)
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.
mxLogical* buffer | Buffer containing data to copy |
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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)
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.
mxChar** buffer | Buffer containing data to copy |
mwSize len | Maximum length of buffer. A maximum of len elements
will be copied. |
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)
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.
mwArray& arr | mwArray that has been obtained by calling mwArray::Serialize |
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)
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.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxDouble* rdata | Data associated with non-zero row and column indices |
mwSize num_rows | Number of rows in matrix |
mwSize num_cols | Number of columns in matrix |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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)
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}.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxDouble* rdata | Data associated with non-zero row and column indices |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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)
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.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxDouble* rdata | Real part of data associated with non-zero row and column indices |
mxDouble* idata | Imaginary part of data associated with non-zero row and column indices |
mwSize num_rows | Number of rows in matrix |
mwSize num_cols | Number of columns in matrix |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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)
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}.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxDouble* rdata | Real part of data associated with non-zero row and column indices |
mxDouble* idata | Imaginary part of data associated with non-zero row and column indices |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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)
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.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxLogical* rdata | Data associated with non-zero row and column indices |
mwSize num_rows | Number of rows in matrix |
mwSize num_cols | Number of columns in matrix |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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)
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}.
mwSize rowindex_size | Size of rowindex array |
mwIndex* rowindex | Array of row indices of non-zero elements |
mwSize colindex_size | Size of colindex array |
mwIndex* colindex | Array of column indices of non-zero elements |
mwSize data_size | Size of data array |
mxLogical* rdata | Data associated with non-zero row and column indices |
mwSize nzmax | Reserved storage for sparse matrix. If nzmax is
zero, storage will be set to max{rowindex_size, colindex_size,
data_size}. |
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) 1static mwArray NewSparse (mwSize num_rows, mwSize num_cols, mwSize nzmax, mxClassID mxID, mxComplexity cmplx = mxREAL)
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.
mwSize num_rows | Number of rows in matrix |
mwSize num_cols | Number of columns in matrix |
mwSize nzmax | Reserved storage for sparse matrix |
mxClassID mxID | Type 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 cmplx | Complexity 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 |
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()
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.
double x = mwArray::GetNaN();
static double GetEps()
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.
double x = mwArray::GetEps();
static double GetInf()
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)returnsInfbecause the result is too large to be represented on your machine.
double x = mwArray::GetInf();
static bool IsFinite(double x)
Determine whether or not a value is finite. A number is finite
if it is greater than -Inf and less than Inf.
double x | Value to test for finiteness |
bool x = mwArray::IsFinite(1.0);
static bool IsInf(double x)
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 equalsNaN(Not-a-Number), thenmxIsInfreturnsfalse. In other words,NaNis not equal to infinity.
double x | Value to test for infiniteness |
bool x = mwArray::IsInf(1.0);
static bool IsNaN(double x)
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.0Inf-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.
double x | Value to test for NaN |
bool x = mwArray::IsNaN(1.0);
Operators
mwArray operator()(mwIndex i1, mwIndex i2, mwIndex i3, ..., )
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.
mwIndex i1, mwIndex i2, mwIndex i3,
..., | Comma-separated list of input indices |
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, ..., )
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.
char* name | Null terminated string containing the field name to get |
mwIndex i1, mwIndex i2, mwIndex i3,
..., | Comma-separated list of input indices |
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)
Sets a single scalar value. This operator is overloaded for all numeric and logical types.
const <type>& x | Value to assign |
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
Fetches a single scalar value. This operator is overloaded for all numeric and logical types.
mwIndex i1, mwIndex i2, mwIndex i3,
..., | Comma-separated list of input indices |
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 &)
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
You can also select a web site from the following list
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)
Asia Pacific
- Australia (English)
- India (English)
- New Zealand (English)
- 中国
- 日本Japanese (日本語)
- 한국Korean (한국어)