C++ Math Library Reference

The mwVarargin and mwVarargout Classes

MATLAB supports functions that accept a variable number of input arguments and return a variable number of return values. The C++ Math Library defines two classes to handle these functions.

• The mwVarargin class
• The mwVarargout class

The mwVarargin Class

MATLAB C++ Math Library functions that take a variable number of input arguments have one mwVarargin argument followed by 31 additional mwArray arguments.

• If you pass 32 or fewer arguments, you can ignore the mwVarargin parameter and simply pass a series of mwArrays as with any other function.
• If you need to pass more than 32 inputs, you must construct an mwVarargin object and pass it as the mwVarargin parameter.

Constructors

The mwVarargin constructor has the standard varargin parameter list: one mwVarargin argument followed by 31 additional mwArray arguments. The mwVarargin constructors can be nested enabling you to pass an unlimited number of inputs.

The inputs used to construct the mwVarargin argument appear first on the argument list for the function, followed by the remaining 31 inputs. It is not necessary to fill out the mwVarargin constructor parameter list. The arguments can be distributed between the mwVarargin constructor and the remaining 31 arguments.

For example, the library function horzcat() is a varargin function that demonstrates the standard varargin parameter list. Its function prototype is

mwArray horzcat(const mwVarargin &in1=mwArray::DIN,
                 const mwArray &in2=mwArray::DIN,
                 .
                 .
                 .
                 const mwArray &in32=mwArray::DIN);

To pass 90 inputs to the horzcat function, make this call:

horzcat(mwVarargin(mwVarargin(p1,p2,...,p32), p33, ..., p63),
        p64, ..., p90);

The first 32 arguments are passed to an mwVarargin constructor that is nested as the first argument to another mwVarargin constructor. The next 31 arguments (p33 through p63) are passed as mwArray arguments to the mwVarargin object that is the first argument to horzcat(). The remaining arguments (p64 through p90) are passed as additional mwArray arguments to the function.

Note that the ... represent omitted aguments in the series and are not part of the actual function prototype or function call.

The mwVarargout Class

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

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

Array Size

Function Reference