Using the C Math Library

Optional Input and Output Arguments

MATLAB functions may have both optional input and optional output arguments. For example, the MATLAB singular value decomposition function svd, supports three syntaxes, each with optional input and output arguments.

s = svd(X)
[U, S, V] = svd(X)
[U, S, V] = svd(X, 0)

The three calls to svd differ both in the number of arguments passed to svd and in the number of values returned by svd. Notice that there is one constant among all three calls - the X input parameter is always present in the parameter list. X is therefore a required argument; the other four arguments (U, S, V, and 0) are optional arguments.

The MATLAB C Math Library function mlfSvd has an argument list that encompasses all the combinations of arguments the MATLAB svd function accepts. All the arguments to mlfSvd are pointers. The return value is a pointer as well. Input arguments and return values are always declared as mxArray*, output arguments as mxArray**.

mxArray *mlfSvd(mxArray **S, mxArray **V, mxArray *X,
                mxArray *Zero);

The return value and the parameters S and V represent the output arguments of the corresponding MATLAB function svd. The parameters X and Zero correspond to the input arguments of svd. Notice that all the output arguments are listed before any input argument appears; this is a general rule for MATLAB C Math Library functions.

mlfSvd has four arguments in its parameter list and one return value for a total of five arguments. Five is also the maximum number of arguments accepted by the MATLAB svd function. Clearly, mlfSvd can accept just as many arguments as svd. But because C does not permit arguments to be left out of a parameter list, there is still the question of how to specify the various combinations.

The svd reference page from the online MATLAB Function Reference indicates that there are three valid combinations of arguments for svd: one input and one output, one input and three outputs, and two inputs and three outputs. All MATLAB C Math Library functions have the same number of inputs and outputs as their MATLAB interpreted counterparts.

mxArray *X;
mxArray *U = NULL, *S = NULL, *V = NULL ;

mlfAssign(&S, mlfSvd(NULL, NULL, X, NULL));
mlfAssign(&U, mlfSvd(&S, &V, X, NULL));
mlfAssign(&U, mlfSvd(&S, &V, X, mlfScalar(0)));

In C, a function can return only one value. To overcome this limitation, the MATLAB C Math Library places all output parameters in excess of the first in the function argument list. The MATLAB svd function can have a maximum of three outputs, therefore the mlfSvd function returns one value and takes two output parameters, for a total of three outputs.

Notice that where the svd function may be called with differing numbers of arguments, the mlfSvd function is always called with the same number of arguments: four; mlfSvd always returns a single value. However, the calls to mlfSvd are not identical: each has a different number of NULLs in the argument list. Each NULL argument takes the place of an "optional" argument.

Optional Output Arguments

Variable Input Arguments