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 library definition file.

  • Pointers representing arrays of C++ class objects

  • Pointers to non-const primitive arrays returned from a function

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

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++ 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 Additional Output Arguments

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