Calling Library Functions (Using the C++ Math Library)

Using the C++ Math Library

Passing Any Number of Outputs

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. Because the arguments are output arguments, they don't need to exist yet. 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 dimensionality of the input argument X is 2, 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 dimensionality is 4, 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 by constructing an mwVarargout object that contains the arguments you are passing. The first output argument is always the return value

size(mwVarargout(d1, d2, d3, d4), X);

where X and d1, d2, d3, and d4 are mwArray objects. Note that you do not pass the address of the mwArray objects to the mwVarargout constructor even though they are output arguments.

Constructing an mwVarargout Object

MATLAB C++ Math Library functions that produce a variable number of outputs have an mwVarargout parameter as their last output argument.

In order to retrieve the varargout outputs from the function, you need to construct an mwVarargout object. You pass the variables to which the outputs will be assigned to the mwVarargout constructor and then pass the mwVarargout object as the last output argument to the function.

The arguments to the mwVarargout constructor differ from normal output arguments in two ways. When constructing an mwVarargout object:

You pass the array itself, not a pointer to the array, to the constructor.

You can pass indexed expressions as inputs. Anything that can appear on the left-hand side of an assignment can appear as an argument to the mwVarargout constructor.

For example, this code demonstrates a call to the M-function size, which takes a variable number of output arguments and a single input argument. The prototype for size() in C++ specifies an mwVarargout object, as its first parameter, and one or two input arguments. The call to size() in C++ corresponds to the call in M.

M code:

[x, y(2,3), z{:}] = size(m)

C++ prototype:

mwArray size(mwVarargout varargout,
             const mwArray &in1,
             const mwArray &in2=mwArray::DIN);

C++ call:

size(mwVarargout(x, y(2,3), z.cell(colon())), m);

Note that the function size() takes no other required output arguments besides a varargout argument. It is called a "pure" varargout function. In pure varargout functions, the return value of the function is the same as the value assigned to the first element of the mwVarargout object, in this case the variable x. When calling a pure varargout function, you do not need to assign the output of the function to the first output argument explicitly; simply pass it to the mwVarargout constructor. For all functions in the MATLAB C++ Math Library, if the first argument is mwVarargout, the function is pure varargout.

If other output arguments precede the mwVarargout parameter, then the return value is not part of the mwVarargout object and must be explicitly assigned to a return value.

Passing Any Number of Inputs Summary of Library Calling Conventions