MATLAB®

MATLAB^® Data

The MATLAB^® Array

The MATLAB^® language works with only a single object type: the MATLAB array. All MATLAB variables, including scalars, vectors, matrices, strings, cell arrays, structures, and objects, are stored as MATLAB arrays. In C, the MATLAB array is declared to be of type mxArray. The mxArray structure contains, among other things:

• 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

Back to Top

Data Storage

All MATLAB data is stored columnwise, which is how Fortran stores matrices. MATLAB uses this convention because it was originally written in Fortran. 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

Back to Top

MATLAB^® Types

Complex Double-Precision Matrices

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 real-only, double-precision matrix is one whose pi is NULL.

Numeric Matrices

MATLAB also supports other types of numeric matrices. These are 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.

Logical 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

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

Cell arrays are a collection of MATLAB arrays where each mxArray is referred to as a cell. This allows 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.

Structures

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

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.

Multidimensional Arrays

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.

Empty Arrays

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.

Back to Top

Sparse Matrices

Sparse matrices have a different storage convention from that of full matrices in MATLAB. The parameters pr and pi are still arrays of double-precision numbers, but these arrays contain only nonzero data elements. There are three additional parameters: nzmax, ir, and jc.

• nzmax is an integer that contains the length of ir, pr, and, if it exists, pi. It is the maximum possible 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. The jc array contains column index information. If the jth column of the sparse matrix has any nonzero elements, jc[j] is the index in ir and pr (and pi if it exists) of the first nonzero element in the jth column, and jc[j+1] - 1 is the index of the last nonzero element in that column. For the jth 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 additional storage.

Back to Top

Using Data Types

You can write source MEX-files, MAT-file applications, and engine applications in C that accept any data type supported by MATLAB. In Fortran, only the creation of double-precision n-by-m arrays and strings are supported. You can treat C and Fortran MEX-files, once compiled, exactly like M-functions.

Caution   MATLAB does not check the validity of MATLAB data structures created in C or Fortran using one of the mx functions (e.g., mxCreateStructArray). Using invalid syntax to create a MATLAB data structure can result in unexpected behavior in your C or Fortran program.

The explore Example

There is an example source MEX-file included with MATLAB, called explore.c, that identifies the data type of an input variable. The source file for this example is in the matlabroot/extern/examples/mex directory, where matlabroot represents the top-level directory where MATLAB is installed on your system.

Note    In platform-independent discussions that refer to directory paths, this book uses the UNIX® convention. For example, a general reference to the mex directory is matlabroot/extern/examples/mex.

For example, typing:

cd([matlabroot '/extern/examples/mex']);
x = 2;
explore(x);

produces this result:

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

Back to Top

Using MEX-Files to Call C and Fortran Programs

Building Binary MEX-Files