Using the C Math Library

Replacing Argument Lists with a Cell Array

In MATLAB you can substitute a cell array for a comma-separated list of MATLAB variables when you pass input arguments to a function. MATLAB treats the contents of each cell as a separate input argument. To trigger this functionality, you specify multiple values by indexing into the cell array with, for example, the colon index or a vector index.

For example, the MATLAB expression

T{1:5}

when passed as an input argument is equivalent to a comma-separated list of the contents of the first five cells of T. Simply passing the cell array T produces an error.

The MATLAB C Math Library also supports the expansion of the contents of a cell array into separate input arguments for library functions. For functions that implement MATLAB varargin functions, you use the indexing function mlfIndexRef() and a cell array index to obtain an array reference that returns multiple values.

For example, given the varargin function

void mlfVarargin_Func(mxArray *A, mxArray *B, ...);

you can make the following call:

mlfVarargin_Func(A,
                 B,
                 mlfIndexRef(C, "{?}",
                      mlfColon(mlfScalar(1), mlfScalar(5), NULL)),
                 NULL);

A and B, pointers to existing mxArrays, are passed as explicit arguments. C is a pointer to a cell array that contains at least five cells. The embedded call to mlfIndexRef() uses the index {1:5} to return multiple values: the first five cells of C. The MATLAB C Math Library passes these as individual arguments to mlfVarargin_Func().

Positioning the Indexed Cell Array

• Pass the return from the cell array indexing operation as one of the variable-length arguments in the input argument list. That reference identifies multiple arrays.
• Do not pass the return from a cell array indexing operation as an explicit argument.

For example, you cannot make this call to the example varargin function.

mlfVarargin_Func(mlfIndexRef(C, "{?}",
                       mlfColon(mlfScalar(1), mlfScalar(5), NULL)),
                 A, B, NULL);

Given the definition of mlfVarargin_Func(), the first argument position is reserved for an explicit, single argument. The MATLAB C Math Library does not handle multiple values in an explicit position.

• You can pass other array arguments or other cell array indexing expressions before or after a cell array indexing expression, all in the ... argument positions.

See Cell Array Indexing to learn more about indexing into cell arrays.

Exception for Built-In Library Functions

For built-in MATLAB C Math Library functions that are varargin functions, for example, mlfCat(), mlfRand(), and mlfOnes()), consider the explicit argument that immediately precedes the ... as part of the varargin arguments. This argument can accept an indexed cell array expression.

For example, in this code the embedded call to mlfIndexRef() is in the position of the explicit argument that precedes the ... in the signature of the built-in function mlfCat().

/* In MATLAB:
 * F{1} = pascal(3);
 * F{2} = magic(3);
 * F{3} = ones(3);
 * F{4} = magic(3);
 * G = cat(2,F{:});
 */

mxArray *F = NULL, *G = NULL;

mlfIndexAssign(&F, "{?}", mlfScalar(1),
                mlfPascal(mlfScalar(3),NULL));
mlfIndexAssign(&F, "{?}", mlfScalar(2),
                mlfMagic(mlfScalar(3)));
mlfIndexAssign(&F, "{?}", mlfScalar(3),
                mlfOnes(mlfScalar(3),NULL));
mlfIndexAssign(&F, "{?}", mlfScalar(4),
                mlfMagic(mlfScalar(3)));

mlfAssign(&G, mlfCat(mlfScalar(2),
           mlfIndexRef(F, "{?}", mlfCreateColonIndex()), NULL));

Example - Passing Functions As Arguments (ex4.c)

Importing and Exporting Array Data