Using the C++ Math Library

Passing Any Number of Inputs

Some MATLAB functions accept any number of input arguments. In MATLAB these functions are called varargin functions. When the variable varargin appears as the last input argument in the definition of a MATLAB function, you can pass any number of input arguments to the function, starting at that position in the argument list.

MATLAB takes the arguments you pass and stores them in a cell array, which can hold any size or kind of data. The varargin function then treats the elements of that cell array exactly as if they were arguments passed to the function.

Whenever you see an ellipsis (...) at the end of the input argument list in a MATLAB syntax description, the function is a varargin function. For example, the syntax for the MATLAB function cat includes the following specification in the online MATLAB Function Reference.

B = cat(dim,A1,A2,A3,A4,...)

cat accepts any number of arguments. The dim and A1 arguments to cat are required. You then concatenate any number of additional arrays along dimension dim. For example, this call concatenates six arrays along the second dimension

B = cat(2,A1,A2,A3,A4,A5,A6)

Because the C++ language does not support functions that accept variable-length argument lists, the MATLAB C++ Math Library supports MATLAB varargin functions through overloading and the mwVarargin class.

In the MATLAB C++ Math Library, you invoke the cat function like this if you are passing 32 or fewer array arguments. The call looks just like the MATLAB call

B = cat(2,A1,A2,A3,A4,A5,A6);

where B and the six A matrices are mwArray objects.

However, if you need to pass more than 32 arguments to a varargin function in the MATLAB C++ Math Library, you must construct an mwVarargin object that you pass as the first argument following any required or optional input arguments. The mwVarargin object stores up to 32 input arguments, the first of which can be another mwVarargin object, allowing you to create any length input argument list.

Constructing an mwVarargin Object

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.

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 arguments in the series and are not part of the actual function prototype or function call.

Note    If a function takes any required output arguments, an mwVarargout argument, or any required or optional input arguments, these arguments precede the first mwVarargin argument in the list of arguments.

Passing Optional Input and Output Arguments

Passing Any Number of Outputs