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
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"]);

Related Topics

• Define MATLAB Interface for C++ Library
• Define Missing DIRECTION Parameter
• Define Missing MLTYPE Parameter