Define Missing SHAPE Parameter

Define Missing `SHAPE` Parameter

In C++, pointer arguments are used for both scalar data and array data. To use a pointer as an array, MATLAB^® needs dimension information to safely convert the array between C++ and MATLAB. The SHAPE parameter helps you specify the dimensions for the pointer.

Note

Pointers representing arrays of C++ class objects can only be used as scalars. Define SHAPE as 1 in the library definition file.

The following example C++ signatures 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.

Define Pointer Argument to Fixed Scalar

C++ Signature and Role of Pointer	`defineArgument` Values
The input to this function 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 this function 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 this function 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 this function 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 this function 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 this function 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 this function 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 this function 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");
The input to this function is a two-dimensional array `mat` of size `len` by `typeSz`. void readMatrix2DArr(int const [] mat, size_t len, size_t typeSz)	For argument `mat`, set `SHAPE` to `["len","typeSz"]`. defineArgument(readMatrix2DArrDefinition, "mat", ... "int32", "input", ["len","typeSz"]);

Define Output Pointer Argument

C++ Signature	`defineArgument` Values
The input to this function 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 input to this function is a pointer to an array of length `len`. The library provides a function named `CustomDeleteFcn` which MATLAB can use to manage the memory of the argument. int const * getRandomValues(size_t len)	For the return value `RetVal`, set `SHAPE` to argument `len`. Specify `CustomDeleteFcn` as the `DeleteFcn` argument. defineOutput(getRandomValuesDefinition, "RetVal", ... "int32", "len", "DeleteFcn", "CustomDeleteFcn");
The output argument of this function 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);
The output argument of this function is a pointer to a 2-by-2 array. double * getRandomValuesArray()	For the return value `RetVal`, set `SHAPE` to a [2, 2] array. defineOutput(getRandomValuesArrayDefinition, ... "RetVal", "double", [2,2]);
The output argument of this function is a pointer to a 1-by-2 vector of type double. The library provides a function named `CustomDeleteFcn` which MATLAB can use to manage the memory of the argument. double * getRandomValuesDouble()	For the return value `RetVal`, set `SHAPE` to 2. Specify `CustomDeleteFcn` as the `DeleteFcn` argument. defineOutput(getRandomValuesDoubleDefinition, ... "RetVal", "double", 2, "DeleteFcn", "CustomDeleteFcn");
The output argument of this function is a pointer to a 1-by-2 vector of type `const` double. The library provides a function named `CustomDeleteFcn` which MATLAB can use to manage the memory of the argument. double const * getRandomConstDouble()	For the return value `RetVal`, set `SHAPE` to 2. Specify `CustomDeleteFcn` as the `DeleteFcn` argument. defineOutput(getRandomConstDoubleDefinition, ... "RetVal", "double", 2, "DeleteFcn", "CustomDeleteFcn");

Define Additional Output Arguments

C++ Signature	`defineArgument` Values
This function returns an integer value and the value to which input argument `arg` points. int getValues(int * arg)	For argument `arg`, change `DIRECTION` to `"output"`, change `MLTYPE` to `"int32"`, and set `SHAPE` to 1. defineArgument(getValuesDefinition, "arg", "int32", "output", 1);
To call the function built into interface `A` from MATLAB, type: [out1, out2] = clib.A.getValues

Define Scalar Object Argument

C++ Signature	`defineArgument` Values
The input to this function 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 this function 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 this function 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 this function 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 this function 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 this function 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 this function 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 this function 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");
This function 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");
This function 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 this function is a C-style 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 this function is a string. char const * getStringCopy(char const * str)	For return value `RetVal`, set `MLTYPE` to `"string"` and `SHAPE` to `"nullTerminated"`. defineOutput(getStringCopyDefinition, ... "RetVal", "string", "nullTerminated");
The return value for this function is a string of length `buf`. void getMessage(char * pmsg, int buf)	MATLAB defines argument `pmsg` as an input variable of type `clib.array.libname.Char`. %defineArgument(getMessageDefinition, "pmsg", ... "clib.array.libname.Char", "input", <SHAPE>); To define `pmsg` as an output variable of type string: Replace `"input"` with `"output"`. Replace the type with `"string"` and set `<SHAPE>` to `"nullTerminated"`. Add the `"NumElementsInBuffer"` name-value argument set to variable `buf`. defineArgument(getMessageDefinition, "pmsg", ... "string, "output", "nullTerminated", ... "NumElementsInBuffer", "buf");
The input to this function 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 this function 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 this function 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 return value for this function is a 2 element character vector. char * getRandomChars()	For return value `RetVal`, set `MLTYPE` to `"char"` and `SHAPE` to `2`. defineOutput(getRandomCharsDefinition, ... "RetVal", "char", 2);
The return value for this function is a 2 element character vector. The library provides a function named `CustomDeleteFcn` which MATLAB can use to manage the memory of the argument. char * getRandomChars()	For return value `RetVal`, set `MLTYPE` to `"char"` and `SHAPE` to `2`. Specify `CustomDeleteFcn` as the `DeleteFcn` argument. defineOutput(getRandomCharsDefinition, ... "RetVal", "char", 2 "DeleteFcn", "CustomDeleteFcn");
The type of the return value for this function is `int8`. char const * getRandomInt8Scalar()	For return value `RetVal`, set `MLTYPE` to `"int8"` and `SHAPE` to `1`. defineOutput(getRandomInt8ScalarDefinition, ... "RetVal", "int8", 1);
This function 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");
The input to these functions is an array of C-string of size `numStrs`. void readCStrArray(char** strs, int numStrs); void readCStrArray(char* strs[], int numStrs);	For argument `strs`, set `SHAPE` to the array `["numStrs", "nullTerminated"]`. defineArgument(readCStrArrayDefinition, ... "strs", "string", "input", ["numStrs", "nullTerminated"])
The input to these functions is a `const` array of C-string of size `numStrs`. void readConstCStrArray (const char** strs, int numStrs); void readConstCStrArray (const char* strs[], int numStrs);	Call `clibgen.generateLibraryDefinition` with `TreatConstCharPointerAsCString` set to true to automatically define `SHAPE` for argument `strs` as `["numStrs", "nullTerminated"]`. defineArgument(readConstCStrArrayDefinition, ... "strs", "string", "input", ["numStrs", "nullTerminated"])
The input to this function is a fixed-size array of C-string. void readFixedCStrArray (char* strs[5]);	For argument `strs`, set `SHAPE` to the array `[5, "nullTerminated"]`. defineArgument(readFixedCStrArrayDefinition, ... "strs", "string", "input", [5, "nullTerminated"])
The input to this function is a fixed-size `const` array of C-string. void readConstCFixedStrArray (const char* strs[5]);	Call `clibgen.generateLibraryDefinition` with `TreatConstCharPointerAsCString` set to true to define `SHAPE` for argument `strs` as `[5, "nullTerminated"]`. defineArgument(readConstFixedCStrArrayDefinition, ... "strs", "string", "input", [5, "nullTerminated"])

Define Typed Pointer Argument

C++ Signature defineArgument Values

C++ Signature	`defineArgument` Values
The input to this function 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 this function 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);

Use Property or Method as `SHAPE`

You can use a public nonstatic C++ data member (property) as the SHAPE for the return type of a nonstatic method or another nonstatic data member (property) in the same class. The property must be defined as an integer (C++ type int). Similarly, you can use a static C++ data members as a SHAPE parameter for a return type of a static method or another static data member in the same class.

You can use a public, nonstatic C++ method as the SHAPE parameter for a nonstatic property or for the return type of a nonstatic method in the same class. The method must be fully implemented, without input arguments, and the return type must be defined as a C++ type int.

You can use a combination of parameters, properties and methods as the SHAPE parameter for a method return type. If the specified SHAPE exists as both a parameter and a method or property, then parameters take precedence. In this case SHAPE is treated as a parameter.

C++ Signature	SHAPE Values
The size of data member `rowData` is defined by data members `rows` and `cols` and by the result of method `channels`. class A { public: int rows; int cols; int* rowData; int channels(); };	For property `rowData`, set `SHAPE` to an array of `rows`, `cols`, and `channels`. addProperty(ADefinition, "rowdata", ["rows","cols","channels"]... "Description", "clib.array.libname.Int Data member of C++ class A.");
The size of the array returned by `getData` is defined by data members `rows` and `cols` and by the result of the `channels` method. class B { public: int rows; int cols; int* rowData; int channels(); const int* getData(); };	For the return value of method `getData`, set `SHAPE` to an array of `rows`, `cols`, and `channels`. defineOutput(getDataDefinition, "RetVal", "clib.array.libname.Int", ... ["rows","cols","channels"]);
The size of the array returned by `getData` is defined by the `rows` parameter and the result of method `channels`. class C { public: int rows; int channels(); const int* getData (int rows); };	For the return value of method `getData`, set `SHAPE` to an array of parameter `rows` and method `channels`. defineOutput(getDataDefinition, "RetVal", "clib.array.C.Int", ["rows","channels"]);