Define Missing Information for MATLAB Signatures

The MATLAB^® interface automatically converts C++ function signatures into MATLAB function signatures. However, some C++ language constructs do not have unique matches in the MATLAB language. To include this functionality in the interface, edit the .mlx definition file and replace the <DIRECTION>, <SHAPE>, and <MLTYPE> parameters with the missing information. These parameters are used for the following cases.

To specify if a pointer argument is read-only input, output only, or a modifiable input argument, use the DIRECTION parameter.
If a pointer argument is used for array data, then dimension information is required to convert the array between C++ and MATLAB. Use the SHAPE parameter to specify this information.
C++ has many types representing string arguments. You might need to specify MLTYPE and SHAPE values so that MATLAB can correctly convert the C++ type to the MATLAB string type.

MATLAB offers code suggestions for values of these parameters. To activate suggestions for a specific parameter:

Uncomment the code defining the function.
Delete the parameter name, including the <> characters.
Pause to allow the code suggestions to display.
If the suggestions do not appear, check that the definelibName.mlx file is on your MATLAB path.

`DIRECTION` Parameter

In C++, pointer arguments can be used to pass and return data from a function. Use the DIRECTION parameter to specify if the argument is read-only input, output only, or a modifiable input argument.

The DIRECTION parameter has one of these values:

input—Input argument only
If a pointer argument is used to pass data to the function, then it must appear as an input argument in the MATLAB signature.
output—Output argument only
If a pointer argument is used to retrieve data from the function, then it must appear as an output argument in the MATLAB signature.
inputoutput—Input and output argument
If a pointer argument is used to both pass and return data, then it must appear as both an input argument and an output argument.

Note

Default arguments with direction specified as OUT are not supported. Define these with DIRECTION as INPUT or INPUTOUTPUT in the MLX file.

For example, suppose that a C++ function passData has the following signature. The argument data might be an input to the function, the return value of the function, or input that the function modifies and returns. The documentation of the function tells you how the function uses the argument data.

void passData(double *data);

Assuming data is a scalar double value, this table shows the MATLAB signature based on its role.

C++ Role for `data`	MATLAB Signature
Input data only to `passData`	% Set DIRECTION = input passData(data)
Return data only from `passData`	% Set DIRECTION = output [data] = passData()
Input and output data for `passData`	% Set DIRECTION = inputoutput [data] = passData(data)

`SHAPE` Parameter

In C++, pointer arguments are used for both scalar data and array data. To use a pointer as an array, dimension information is required to convert the array between C++ and MATLAB. The SHAPE parameter specifies the dimensions for the pointer.

Note

These pointer types can only be used as scalars. Define SHAPE as 1 in the MLX file.

Pointers representing arrays of C++ class objects
Pointers to non-const primitive arrays returned from a function

The following examples of constructs defined in the sample cppUseCases.hpp header file show you how to specify the shape of an argument. In these tables, the descriptions for the functions in the C++ Signature and Role of Pointer column are based on assumed knowledge of the arguments. The signature itself does not provide this information.

To view the cppUseCases.hpp header file and its generated definition file, see Sample C++ Library Definition File.

Define Pointer Argument to Fixed Scalar

C++ Signature and Role of Pointer	`defineArgument` Values
The input to function `readScalarPtr` is a scalar pointer `in`. void readScalarPtr(int const * in)	For argument `in`, set `SHAPE` to `1`. defineArgument(readScalarPtrDefinition, "in", ... "int32", "input", 1);
The input to function `readScalarPtr` is a scalar pointer to class `ns::MyClass2`. void readScalarPtr(ns::MyClass2 const * in)	For argument `in`, set `SHAPE` to `1`. defineArgument(readScalarPtrDefinition, "in", ... "clib.cppUseCases.ns.MyClass2", "input", 1);

Define Pointer Argument

C++ Signature	`defineArgument` Values
The input to function `readMatrix1DPtr` is a pointer to an integer array of length `m`. void readMatrix1DPtr(int const * mat, size_t m)	For argument `mat`, set `SHAPE` to argument `m`. defineArgument(readMatrix1DPtrDefinition, "mat", ... "int32", "input", "m");
The input to function `readMatrix1DPtrFixedSize` is a pointer to a fixed-length array `mat`. void readMatrix1DPtrFixedSize(int const * mat)	For argument `mat`, set `SHAPE` to a fixed integer, such as 5. defineArgument(readMatrix1DPtrFixedSizeDefinition, ... "mat", "int32", "input", 5);
The input to function `readMatrix2DPtr` is a pointer to a two-dimensional integer matrix `mat` of size `m`-by-`n`. void readMatrix2DPtr(int const * mat, size_t m, size_t n)	For argument `mat`, set `SHAPE` to `["m","n"]`. defineArgument(readMatrix2DPtrDefinition, "mat", ... "int32", "input", ["m","n"]);
The input to function `readMatrix2DPtrFixedSize` is a pointer to a two-dimensional matrix `mat` of fixed dimensions. void readMatrix2DPtrFixedSize(int const * mat)	For argument `mat`, set `SHAPE` to a fixed integer, such as 6. defineArgument(readMatrix2DPtrFixedSizeDefinition, ... "mat", "int32", "input", 6);
The input to function `readMatrix3DPtr` is a pointer to a three-dimensional matrix `mat` of size `m`-by-`n`-by-`p`. void readMatrix3DPtr(int const * mat, size_t m, size_t n, size_t p)	For argument `mat`, set `SHAPE` to `["m","n","p"]`. defineArgument(readMatrix3DPtrDefinition, "mat", ... "int32", "input", ["m","n","p"]);

Define Array Argument

C++ Signature	`defineArgument` Values
The input to function `readMatrix1DArr` is a one-dimensional array `mat` of length `len`. void readMatrix1DArr(int const [] mat, size_t len)	For argument `mat`, set `SHAPE` to length `len`. defineArgument(readMatrix1DArrDefinition, "mat", ... "int32", "input", "len");

Define Output Pointer Argument

C++ Signature	`defineArgument` Values
The input to function `getRandomValues` is a pointer to an array of length `len`. The function returns a pointer argument as output. int const * getRandomValues(size_t len)	For the return value `RetVal`, set `SHAPE` to argument `len`. defineOutput(getRandomValuesDefinition, "RetVal", ... "int32", "len");
The output argument of function `getRandomValuesFixedSize` is a pointer to a fixed-length array. int const * getRandomValuesFixedSize()	For the return value `RetVal`, set `SHAPE` to an integer, such as 5. defineOutput(getRandomValuesFixedSizeDefinition, ... "RetVal", "int32", 5);

Define Scalar Object Argument

C++ Signature	`defineArgument` Values
The input to function `addClassByPtr` is a pointer to class `ns::MyClass2`. double addClassByPtr(ns::MyClass2 const * myc2)	For the `myc2` argument, set `SHAPE` to `1`. defineArgument(addClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to function `updateClassByPtr` is a pointer to class `ns::MyClass2`. void updateClassByPtr(ns::MyClass2 * myc2, double a, short b, long c)	For argument `myc2`, set `SHAPE` to `1`. defineArgument(updateClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to function `readClassByPtr` is a pointer to class `ns::MyClass2`. void readClassByPtr(ns::MyClass2 * myc2)	For argument `myc2`, set `SHAPE` to `1`. defineArgument(readClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);
The input to function `fillClassByPtr` is a pointer to class `ns::MyClass2`. void fillClassByPtr(ns::MyClass2 * myc2, double a, short b, long c)	For argument `myc2`, set `SHAPE` to `1`. defineArgument(fillClassByPtrDefinition, "myc2", ... "clib.cppUseCases.ns.MyClass2", "input", 1);

Define Matrix Argument

C++ Signature	`defineArgument` Values
The input to function `updateMatrix1DPtrByX` is a pointer to an integer vector of length `len`. The argument `x` modifies the input argument. void updateMatrix1DPtrByX(int * mat, size_t len, int x)	For argument `mat`, set `DIRECTION` to `inputoutput` and `SHAPE` to `len`. defineArgument(updateMatrix1DPtrByXDefinition, ... "mat", "int32", "inputoutput", "len");
The input to function `updateMatrix1DArrByX` is a reference to an integer array of length `len`. Argument `x` modifies input argument `mat`. void updateMatrix1DArrByX(int [] mat, size_t len, int x)	For argument `mat`, set `DIRECTION` to `inputoutput` and `SHAPE` to `len`. defineArgument(updateMatrix1DArrByXDefinition, ... "mat", "int32", "inputoutput", "len");
The input to function `addValuesByPtr` is a pointer to an integer vector of length `len`. The function does not modify the input argument. int addValuesByPtr(int * mat, size_t len)	For argument `mat`, set `DIRECTION` to `input` and `SHAPE` to `len`. defineArgument(addValuesByPtrDefinition, "mat", ... "int32", "input", "len");
The input to function `addValuesByArr` is a reference to an integer array of length `len`. The function does not modify the input argument. int addValuesByArr(int [] mat, size_t len)	For argument `mat`, set `DIRECTION` to `input` and `SHAPE` to `len`. defineArgument(addValuesByArrDefinition, ... "mat", "int32", "input", "len");
The function `fillRandomValuesToPtr` creates an integer vector of length `len` and returns a reference to the vector. void fillRandomValuesToPtr(int * mat, size_t len)	For argument `mat`, set `DIRECTION` to `output` and `SHAPE` to `len`. defineArgument(fillRandomValuesToPtrDefinition, ... "mat", "int32", "output", "len");
The function `fillRandomValuesToArr` creates an integer vector of length `len` and returns a reference to the vector. void fillRandomValuesToArr(int [] mat, size_t len)	For argument `mat`, set `DIRECTION` to `output` and `SHAPE` to `len`. defineArgument(fillRandomValuesToArrDefinition, ... "mat", "int32", "output", "len");

Define String Argument

C++ Signature	`defineArgument` Values
The input to function `getStringCopy` is a null-terminated string. char const * getStringCopy(char const * str)	For argument `str`, set `MLTYPE` to `string` and `SHAPE` to `nullTerminated`. defineArgument(getStringCopyDefinition, "str", ... "string", "input", "nullTerminated");
The return value for function `getStringCopy` is a scalar of characters. char const * getStringCopy(char const * str)	For return value `RetVal`, set `MLTYPE` to `char` and `SHAPE` to `1`. defineOutput(getStringCopy, "RetVal", "char", 1);
The input to function `readCharArray` is a string specified by length `len`. void readCharArray(char const * chArray, size_t len)	For argument `chArray`, set `MLTYPE` to `char` and `SHAPE` to `len`. defineArgument(readCharArrayDefinition, "chArray", ... "char", "input", "len");
The input to function `readInt8Array` is an array of type `int8` and length `len`. void readInt8Array(char const * int8Array, size_t len)	For argument `int8Array`, set `MLTYPE` to `int8` and `SHAPE` to `len`. defineArgument(readInt8ArrayDefinition, "int8Array", ... "int8", "input", "len");
The return value for function `getRandomCharScalar` is a scalar of characters. char const * getRandomCharScalar()	For return value `RetVal`, set `MLTYPE` to `char` and `SHAPE` to `1`. defineOutput(getRandomCharScalarDefinition, ... "RetVal", "char", 1);
The type of the return value for function `getRandomInt8Scalar` is `int8`. char const * getRandomInt8Scalar()	For return value `RetVal`, set `MLTYPE` to `int8` and `SHAPE` to `1`. defineOutput(getRandomInt8ScalarDefinition, ... "RetVal", "int8", 1);
The function `updateCharArray` updates the input argument `chArray`. The length of `chArray` is `len`. void updateCharArray(char * chArray, size_t len)	For argument `chArray`, set `DIRECTION` to `inputoutput` and `SHAPE` to `len`. defineArgument(updateCharArrayDefinition, ... "chArray", "int8", "inputoutput", "len");

Define Typed Pointer Argument

C++ Signature defineArgument Values

C++ Signature	`defineArgument` Values
The input to function `useTypedefPtr` is a pointer to typedef `intDataPtr`. void useTypedefPtr(intDataPtr input1) `intDataPtr` is defined as: typedef int16_t intData; typedef intData * intDataPtr;	For argument `input1`, set `DIRECTION` to `input` and `SHAPE` to `1`. defineArgument(useTypedefPtrDefinition, "input1", ... "int16", "input", 1);

The input to function useTypedefPtr is a pointer to typedef intDataPtr.

void useTypedefPtr(intDataPtr input1)

intDataPtr is defined as:

typedef int16_t intData;
typedef intData * intDataPtr;

For argument input1, set DIRECTION to input and SHAPE to 1.

defineArgument(useTypedefPtrDefinition, "input1", ...
    "int16", "input", 1);

`MLTYPE` Parameter

MATLAB automatically converts C++ types to MATLAB types, as described in MATLAB to C++ Data Type Mapping. If the C++ type for the argument is a string, then use these options to choose values for the MLTYPE and SHAPE arguments.

C++ Type	`MLTYPE`	Options for `SHAPE`
`char *`	`int8`	Scalar value Array of scalar values
`const char *`	`char`	Scalar value Array of scalar values
`const char *`	`string`	`"nullTerminated"`

Documentation