The MATLAB^{®} language works with a single object type: the MATLAB array.
All MATLAB variables (including scalars, vectors, matrices, character
arrays, cell arrays, structures, and objects) are stored as MATLAB arrays.
In C/C++, the MATLAB array is declared to be of type mxArray
. The mxArray
structure
contains the following information about the array:
Its type
Its dimensions
The data associated with this array
If numeric, whether the variable is real or complex
If sparse, its indices and nonzero maximum elements
If a structure or object, the number of fields and field names
To access the mxArray
structure, use the
API functions in the Matrix Library. These functions allow you to
create, read, and query information about the MATLAB data in
your MEX files. Matrix Library functions use the mwSize
type to avoid portability issues
and allow MEX source files to be compiled correctly on all systems.
Like MATLAB functions, a MEX-file gateway routine passes MATLAB variables by reference. However, these arguments are C pointers. A pointer to a variable is the address (location in memory) of the variable. MATLAB functions handle data storage for you automatically. When passing data to a MEX-file, you use pointers, which follow specific rules for accessing and manipulating variables. For information about working with pointers, refer to a programming reference, such as The C Programming Language by Kernighan, B. W., and D. M. Ritchie.
Note:
Since variables use memory, you need to understand how your
MEX-file creates an |
An mxArray
passed to a MEX-file through the prhs
input
parameter exists outside the scope of the MEX-file. Do not free memory
for any mxArray
in the prhs
parameter.
Additionally, prhs
variables are read-only; do
not modify them in your MEX-file.
If you create an mxArray
(allocate memory
and create data) for an output argument, the memory and data exist
beyond the scope of the MEX-file. Do not free memory on an mxArray
returned
in the plhs
output parameter.
You allocate memory whenever you use an mxCreate*
function
to create an mxArray
or when you call the mxCalloc
and
associated functions. After observing the rules for handling input
and output arguments, the MEX-file should destroy temporary arrays
and free dynamically allocated memory. To deallocate memory, use either mxDestroyArray
or mxFree
.
Refer to the MX
Matrix Library function documentation for information about
which function to use.
MATLAB stores data in a column-major (columnwise) numbering scheme, which is how Fortran stores matrices. MATLAB uses this convention because it was originally written in Fortran. MATLAB internally stores data elements from the first column first, then data elements from the second column second, and so on, through the last column.
For example, given the matrix:
a = ['house'; 'floor'; 'porch']
a = house floor porch
its dimensions are:
size(a)
ans = 3 5
and its data is stored as:
If a matrix is N-dimensional, MATLAB represents the data
in N-major order. For example, consider a three-dimensional array
having dimensions 4
-by-2
-by-3
.
Although you can visualize the data as:
MATLAB internally represents the data for this three-dimensional array in the following order:
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X |
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 |
The mxCalcSingleSubscript
function
creates the offset from the first element of an array to the desired
element, using N-dimensional subscripting.
The most common data type in MATLAB is the complex double-precision,
nonsparse matrix. These matrices are of type double
and
have dimensions m
-by-n
, where m
is
the number of rows and n
is the number of columns.
The data is stored as two vectors of double-precision numbers—one
contains the real data and one contains the imaginary data. The pointers
to this data are referred to as pr
(pointer to
real data) and pi
(pointer to imaginary data),
respectively. A noncomplex matrix is one whose pi
is NULL
.
MATLAB supports single-precision floating-point and 8-, 16-, and 32-bit integers, both signed and unsigned. The data is stored in two vectors in the same manner as double-precision matrices.
The logical data type represents a logical true
or false
state
using the numbers 1
and 0
, respectively.
Certain MATLAB functions and operators return logical 1
or
logical 0
to indicate whether a certain condition
was found to be true or not. For example, the statement (5
* 10) > 40
returns a logical 1
value.
MATLAB strings are of type char
and
are stored the same way as unsigned 16-bit integers except there is
no imaginary data component. Unlike C, MATLAB strings are not
null terminated.
Cell arrays are a collection of MATLAB arrays where each mxArray
is
referred to as a cell. Cell arrays allow MATLAB arrays of different
types to be stored together. Cell arrays are stored in a similar manner
to numeric matrices, except the data portion contains a single vector
of pointers to mxArrays
. Members of this vector
are called cells. Each cell can be of any supported data type, even
another cell array.
A 1
-by-1
structure is
stored in the same manner as a 1
-by-n
cell
array where n
is the number of fields in the structure.
Members of the data vector are called fields. Each field is associated
with a name stored in the mxArray
.
Objects are stored and accessed the same way as structures. In MATLAB, objects are named structures with registered methods. Outside MATLAB, an object is a structure that contains storage for an additional class name that identifies the name of the object.
MATLAB arrays of any type can be multidimensional. A vector of integers is stored where each element is the size of the corresponding dimension. The storage of the data is the same as matrices.
MATLAB arrays of any type can be empty. An empty mxArray
is
one with at least one dimension equal to zero. For example, a double-precision mxArray
of
type double
, where m
and n
equal
0 and pr
is NULL
, is an empty
array.
Sparse matrices have a different storage convention from full
matrices in MATLAB. The parameters pr
and pi
are
still arrays of double-precision numbers or logical values, but these arrays
contain only nonzero data elements. pi
contains data only if the
sparse matrix is complex.
There are three additional
parameters: nzmax
, ir
, and jc
. Use the mwSize
and mwIndex
types when declaring variables
for these parameters.
nzmax
is an integer that contains
the length of ir
, pr
, and pi
,
if it exists. It is the maximum number of nonzero elements in the
sparse matrix.
ir
points to an integer array of
length nzmax
containing the row indices of the
corresponding elements in pr
and pi
.
jc
points to an integer array of
length n+1
, where n
is the number
of columns in the sparse matrix. Note that in C, the first element of an mxArray
has
an index of 0. The jc
array contains
column index information. If the j
th column of
the sparse matrix has any nonzero elements, jc[j]
is
the index into ir
, pr
, and pi
of
the first nonzero element in the j
th column. Index jc[j+1]
- 1
contains the last nonzero element in that column. For
the j
th column of the sparse matrix, jc[j]
is
the total number of nonzero elements in all preceding columns. The
last element of the jc
array, jc[n]
,
is equal to nnz
, the number of nonzero elements
in the entire sparse matrix. If nnz
is less than nzmax
,
more nonzero entries can be inserted into the array without allocating
more storage.
You can write source MEX files, MAT-file applications, and engine
applications in C/C++ that accept any class or data type supported
by MATLAB (see Data Types). In Fortran, only the creation of double-precision n
-by-m
arrays
and strings are supported. You use binary C/C++ and Fortran MEX files
like MATLAB functions.
Caution
MATLAB does not check the validity of MATLAB data
structures created in C/C++ or Fortran using one of the Matrix Library
create functions (for example, |
To handle MATLAB arrays, use type mxArray
.
The following statement declares an mxArray
named myData
:
mxArray *myData;
To define the values of myData
, use one of
the mxCreate*
functions. Some useful array creation
routines are mxCreateNumericArray
, mxCreateCellArray
,
and mxCreateCharArray
. For example, the following
statement allocates an m
-by-1
floating-point mxArray
initialized
to 0
:
myData = mxCreateDoubleMatrix(m, 1, mxREAL);
C/C++ programmers should note that data in a MATLAB array
is in column-major order. (For an illustration, see Data Storage.) Use the MATLAB mxGet*
array
access routines to read data from an mxArray
.
The mxGet*
array access routines get references
to the data in an mxArray
. Use these routines to
modify data in your MEX file. Each function provides access to specific
information in the mxArray
. Some useful functions
are mxGetData
, mxGetPr
, mxGetM
,
and mxGetString
. Many of these functions have
corresponding mxSet*
routines to allow you to modify
values in the array.
The following statements read the input prhs[0]
into
a C-style string buf
.
char *buf; int buflen; int status; buflen = mxGetN(prhs[0])*sizeof(mxChar)+1; buf = mxMalloc(buflen); status = mxGetString(prhs[0], buf, buflen);
There is an example source MEX file included with MATLAB,
called explore.c
,
that identifies the data type of an input variable. The source code
for this example is in matlabroot
/extern/examples/mex
,
where matlabroot
represents the top-level
folder where MATLAB is installed on your system.
Note:
In platform-independent discussions that refer to folder paths,
this documentation uses the UNIX^{®} convention. For example, a general
reference to the |
To build the example MEX file, first copy the file to a writable folder on your path.
copyfile(fullfile(matlabroot,'extern','examples','mex','explore.c'),'.','f')
Use the mex
command to build the MEX file.
mex -largeArrayDims explore.c
Type:
x = 2; explore(x)
------------------------------------------------ Name: prhs[0] Dimensions: 1x1 Class Name: double ------------------------------------------------ (1,1) = 2
explore
accepts any data type. Try using explore
with
these examples:
explore([1 2 3 4 5]) explore 1 2 3 4 5 explore({1 2 3 4 5}) explore(int8([1 2 3 4 5])) explore {1 2 3 4 5} explore(sparse(eye(5))) explore(struct('name', 'Joe Jones', 'ext', 7332)) explore(1, 2, 3, 4, 5)