Note: This page has been translated by MathWorks. Please click here

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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.

Since variables use memory, you need to understand how your MEX-file creates an
`mxArray`

and your responsibility for releasing (freeing) the
memory. This is important to prevent memory leaks. The lifecycle of an
`mxArray`

—and the rules for managing memory—depends
on whether it is an input argument, output argument, or local variable. The function you
call to deallocate an `mxArray`

depends on the function you used to
create it. For more information, look up the function in Create or Delete Array in the C
Matrix Library.

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`

.
For information about which function to use, see MX
Matrix Library.

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.

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, `mxCreateStructArray`

).
Using invalid syntax to create a MATLAB data structure can result
in unexpected behavior in your C/C++ or Fortran program.

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.

In platform-independent discussions that refer to folder paths,
this documentation uses the UNIX^{®} convention. For example, a general
reference to the `mex`

folder is `matlabroot`

`/extern/examples/mex`

.

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 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)

Was this topic helpful?