Calling Conventions (MATLAB C++ Math Library)

Introduction

This section demonstrates the calling conventions that apply to the MATLAB C++ Math Library functions, including what data type to use for C++ input and output arguments, how to handle optional arguments, and how to handle MATLAB's multiple output values in C++.

Refer to the "How to Call C++ Library Functions" section of Chapter 5 in the MATLAB C++ Math Library User's Guide for further discussion of the MATLAB C++ Math Library calling conventions and for a list of exceptions to the calling conventions. Also, see the mwVarargin and mwVarargout reference pages for information on how to call functions that can take any number of input or output arguments.

How the C++ Prototypes Are Constructed

A complete set of C++ prototypes appears on the reference page for each function. You can reconstruct the C++ prototypes for a library function by examining the MATLAB syntax for a function. In C++ an overloaded version of the function exists for each different way of calling the MATLAB function.

In this example, the MATLAB function svd() and the corresponding MATLAB C++ Math Library function svd() are used to illustrate the process.

MATLAB Syntax

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

In this example, the prototype that corresponds to [U,S,V] = svd(X,0) is constructed step-by-step. Until the last step, the prototype is incomplete.

Adding the Output Arguments

1.: Subtract out the first output argument, U, to be the return value from the function. The data type for the return value is mwArray.

mwArray svd(

2.: Add the remaining number of output arguments, S and V, to the prototype as the first, second, etc., arguments to the function. The data type for an output argument is mwArray *.

mwArray svd(mwArray *S, mwArray *V,

Adding the Input Arguments

3.: Add the number of input arguments to the prototype, X and Zero, one after another following the output arguments. The data type for an input argument is mwArray.

mwArray svd(mwArray *S, mwArray *V, const mwArray &X,
                const mwArray &Zero);

The prototype is complete. Repeat the three steps for each call in the "MATLAB Syntax" section.

Note Contrast the data type for an output argument with the data type for an input argument. The type for an output argument is a pointer to an mwArray. The type for an input argument is an mwArray. The const mwArray & in the prototype improves the efficiency of the function, but you can ignore the const and & and just pass in an mwArray.)

How to Translate a MATLAB Call into a C++ Call

This procedure translates the MATLAB call [U,S,V] = svd(X,0) into a C++ call. The procedure applies to library functions in general.

Note that within a call to a MATLAB C++ Math Library function, an output argument is preceded by &; an input argument is not.

1.: Declare input, output, and return variables as mwArray variables, and assign values to the input variables.

2.: Make the first MATLAB output argument the return value from the function.

U =

3.: Pass any other output arguments as the first arguments to the function.

U = svd(&S,&V,

4.: Pass the input arguments to the C++ function, following the output arguments.

U = svd(&S,&V,X,0);

The translation is complete.

Note that if you see [] as a MATLAB input argument, you should pass mwArray() as the C++ argument. For example,

B = cplxpair(A,[],dim)

: becomes

B = cplxpair(A,mwArray(),dim);

[ Previous | Help Desk | Next ]