Using the C Math Library

Variable Output Arguments

Some MATLAB functions return any number of outputs. In MATLAB these functions are called varargout functions. When the variable varargout appears as the last output argument in the definition of a MATLAB function, that function can return any number of outputs, starting at that position in the argument list.

When you call a varargout function in the interpreted MATLAB environment, MATLAB takes the arguments you pass and stores them in the cell array called varargout. A cell array can hold any size or kind of data. The MATLAB function accesses the varying number of arguments passed to it through the cell array.

Whenever you see ... (an ellipsis) within the output argument list of a MATLAB syntax description, the function is a varargout function. For example, this syntax in the online MATLAB Function Reference specifies a version of the MATLAB function size that returns a variable number of outputs depending on the number of dimensions in the array passed to it.

[M1,M2,M3,...,MN] = size(X)

If the input argument X is a two-dimensional array, size returns the length of the first dimension in the first output value and the length of the second dimension in a second output value. If the input argument is a four dimensional array, it returns four lengths.

For example, if the input array, X, has four dimensions, this code retrieves the length of each dimension.

[d1,d2,d3,d4] = size(X)

In the MATLAB C Math Library you invoke the same call to size like this

mlfSize(mlfVarargout(&d1,&d2,&d3,&d4,NULL),X,NULL));

where X, d1, d2, d3, and d4 are mxArray * variables. d1, d2, d3, and d4 are each initialized to NULL. The final input argument to mlfSize() is an optional input argument; in this version of the function, that argument is not used, and NULL is passed.

Note    mlfSize() is what's called a pure varargout function. Pure varargout functions have no required or optional outputs, and no return value. The variable that would ordinarily be used to store the return value must instead be passed to the pure varargout function as the first argument of the mlfVarargout() routine.

Constructing an mlfVarargoutList

You recognize a varargout function prototype in the library by its argument of type mlfVarargoutList. The MATLAB C Math Library positions an mlfVarargoutList structure as the last output argument for functions that can return any number of output values, for example,

mxArray *mlfVarargout_function(mxArray **y,
                               mlfVarargoutList *varargout,
                               mxArray *a,
                               mxArray *b);

An mlfVarargoutList is always the last output argument passed to the function. Any required and optional arguments precede it.

The MATLAB C Math Library provides two functions that construct an mlfVarargoutList structure: mlfVarargout() and mlfIndexVarargout(). Whether you pass indexed varargout arguments to the varargout function determines which function you use:

• Use mlfVarargout() if you're not applying a subscript to any of your varargout output arguments.
• Use mlfIndexVarargout() if you are applying a subscript to at least one of your varargout output arguments.

Forming a List of Non-Indexed varargout Arguments.   If you are not indexing into any of the arrays that you pass as varargout output arguments, you form an mlfVarargoutList by passing the address of each mxArray* to mlfVarargout(). Its prototype is

mlfVarargoutList *mlfVarargout(mxArray **pp_array, ...);

Follow these guidelines when you call mlfVarargout():

• Pass any number of mxArray** variables to mlfVarargout()
• Terminate your list of arguments with NULL

For example, if you want to pass three varargout output arguments to the example varargout function mlfVarargout_Function presented above, embed a call to mlfVarargout() as the second argument

mlfAssign(&x,
          mlfVarargout_Function(&y,
                                mlfVarargout(&z, &m, &n, NULL),
                                a,
                                b);

where all variables are mxArray* pointers. x is the return value; y is a required output argument. z, m, and n are varargout output mxArray* variables. a and b are input variables. Note that this function is not a pure varargout function.

In MATLAB, the function call looks like this.

[x, y, z, m, n] = mlfVarargout_Function (a, b);

Forming a List of Indexed varargout Arguments.   If you are indexing into at least one of the arrays that you pass as a varargout output argument, you must form your mlfVarargoutList by passing indexed and nonindexed arguments to mlfIndexVarargout(), follow these guidelines:

• Pass an indexed array as a series of arguments, just as you do when indexing an array with mlfIndexRef():
• The address of the pointer to the array (mxArray **)
• The index string
• The index subscripts
• Pass each non-indexed array as:
• The address of the pointer to the array (mxArray **)
• A NULL argument
• Terminate your entire list of arguments with NULL.

For example, if you want to pass three varargout output arguments, two of which are indexed, to the example varargout function mlfVarargout_Function presented above, embed a call to mlfindexVarargout() as the second argument.

In MATLAB, the function call looks like this.

 [x, y, z(1), m, n{:}] = mlfVarargout_Function(a, b)

In C, the function call looks like this.

mxArray *x = NULL, *y = NULL, *z = NULL, *m = NULL, *n = NULL;

mlfAssign(&x, mlfVarargout_Function(&y,
                 mlfIndexVarargout(&z, "(?)", mlfScalar(1),
                                   &m, NULL,
                                   &n, "{?}", mlfCreateColonIndex(),
                                   NULL),
                 a, b)));

Pure Varargout Functions

Some MATLAB functions define a varargout argument as their only output argument, and are, therefore, called pure varargout functions. For example,

function [varargout] = Example_Pure_Varargout(a, b)

declares a pure varargout function in MATLAB.

The MATLAB C Math Library requires that you pass all varargout output arguments to mlfVarargout() or mlfIndexVarargout(). The variable that would ordinarily be used to store the return value must instead be passed to the pure varargout function as the first argument of the mlfVarargout() routine.

You construct an mlfVarargoutList by passing any number of array arguments to the function mlfVarargout() or any mix of indexed and non-indexed array arguments to mlfIndexVarargout().

Variable Input Arguments

Summary of Library Calling Conventions