Main Content

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

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 PointerdefineArgument 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++ SignaturedefineArgument 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++ SignaturedefineArgument 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");

Define Output Pointer Argument

C++ SignaturedefineArgument 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 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);

Define Scalar Object Argument

C++ SignaturedefineArgument 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++ SignaturedefineArgument 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++ SignaturedefineArgument 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 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++ SignaturedefineArgument 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++ SignatureSHAPE 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"]);