defineArgument

Class: clibgen.FunctionDefinition
Namespace: clibgen

Add input argument definition for C++ package function

Syntax

defineArgument(FunctionDefinition,CPPName,MATLABType)

defineArgument(FunctionDefinition,CPPName,MATLABType,Direction)

defineArgument(FunctionDefinition,CPPName,MATLABType,Direction,Shape)

defineArgument(___,Name,Value)

Description

defineArgument(FunctionDefinition,CPPName,MATLABType) adds an input argument definition for a C++ package function.

defineArgument(FunctionDefinition,CPPName,MATLABType,Direction) defines whether argument is input, output, or both.

defineArgument(FunctionDefinition,CPPName,MATLABType,Direction,Shape) provides information about data dimensions.

defineArgument(___,Name,Value) adds additional argument definition options specified by one or more Name,Value pair arguments, and can include any of the input parameters in previous syntaxes.

Input Arguments

FunctionDefinition — Function definition

clibgen.FunctionDefinition

Function definition, specified as a clibgen.FunctionDefinition object.

CPPName — C++ argument name

string scalar | character vector

C++ argument name, specified as a string scalar or a character vector.

MATLABType — MATLAB type

string scalar | character vector

MATLAB^® type, specified as a string scalar or a character vector. For more information, see Define Missing MLTYPE Parameter.

Direction — Argument type

"input" (default) | "output" | "inputoutput"

Argument type, specified as "input" for an input argument, "output" for an output argument, or "inputoutput" for both an input and an output argument. For more information, see Define Missing DIRECTION Parameter.

Shape — Dimension definition

string vector | scalar text | positive integer vector | "nullTerminated" | cell array

Dimension definition used by MATLAB to define data dimensions, specified as a string vector, scalar text, positive integer vector, "nullTerminated", or a cell array. For a cell array, the elements are a combination of scalar text and scalar positive integers. For more information, see Define Missing SHAPE Parameter.

If you can define the argument dimension as a fixed scalar value, then enter a number, such as 5.

If the dimension is defined by another argument, then enter the argument name as a string. For example, consider the following C++ signature. If argument len defines the length of data, then the value of Shape is "len".

myFunc(const int *data, int len)

If the size of an argument is defined by an array, then the value of Shape is one of the following:

• 1

• Fixed dimensions: Enter a numerical array, such as [5,2].

• Variable dimensions: Enter a string array of parameter names, such as ["row","col"].

If the C++ type for the argument is a string, then use these options to choose values for the MATLABType and Shape arguments.

C++ Type	MATLABType	DIRECTION	Options for SHAPE
char*a	"int8"	"input"	Scalar value Array of scalar values
char** char*[]	"string"	"input"	cell
const char*	"char"		Scalar value Array of scalar values
	"string"	"input"	"nullTerminated"
const char** const char*[]	"char"	"input"	Scalar value Array of scalar values
	"string"	"input"	"nullTerminated"
a These types are equivalent to MATLAB char: wchar_t char16_t char32_t

For more information, see C++ to MATLAB Data Type Mapping.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Description — C++ argument description

string scalar | character vector

C++ argument description, specified as a string scalar or a character vector. This value sets the Description property.

ReleaseOnCall — Transfer memory ownership of argument

false or 0 (default) | true or 1

Transfer memory ownership of argument, specified as a numeric or logical 1 (true) or 0 (false). MATLAB owns memory that is allocated as a pointer or a reference for an input argument. The C++ library should not free this memory. To change this behavior for a non-const argument, set 'ReleaseOnCall' to true.

The 'ReleaseOnCall' argument is not supported for:

• const arguments.

• Double pointer (obj** or void**) arguments defined as output.

If 'ReleaseOnCall' is not specified, then ReleaseOnCall is false.

For more information, see Lifetime Management of C++ Objects in MATLAB.

Example: 'ReleaseOnCall',true

Data Types: logical

AddTrailingSingletons — Where to pad dimensions

false or 0 (default) | true or 1

Where to pad dimensions, specified as a numeric or logical 1 (true) or 0 (false). By default, when a MATLAB input has fewer dimensions than the corresponding C++ argument, then MATLAB inserts singleton dimensions at the beginning of the Shape argument. To insert singleton dimensions at the end, set 'AddTrailingSingletons' to true. For more information , see Dimension Matching.

Example: 'AddTrailingSingletons',true

Data Types: logical

NumElementsInBuffer — Size of buffer for null-terminated C++ string argument

numeric scalar | string scalar | character vector

The size of a buffer for a null-terminated C++ string argument, specified as a numeric scalar, string scalar, or character vector. The size is the number of C++ elements in the buffer. Use NumElementsInBuffer for MLTYPE value "string" and for DIRECTION value "output". To specify:

• A fixed size value, use a numeric scalar.

• A fixed size array, the value must be the same as the size of the array.

• The name of another parameter, use a string scalar or character vector. The parameter must be an integer value.

Use this buffer to define an argument for a null-terminated string argument returned by a C++ function. MATLAB converts a null-terminated C++ string to a MATLAB string.

The NumElementsInBuffer argument does not support:

• const types

• void *

For an example, see the getMessage function in the Define String Argument table.

Example: "NumElementsInBuffer", "bufLen"

DeleteFcn — Deleter function

string scalar | character vector

Deleter function, specified as a string scalar or character vector. The deleter can be the C++ standard delete operator or a user-defined function. Use 'DeleteFcn' for functions that have a double pointer input argument, for example, void** or object**.

When you specify 'DeleteFcn', then MATLAB takes ownership and manages the lifecycle of the memory represented by the argument. If 'DeleteFcn' is not specified, then the library is responsible for managing the memory.

If you specify a library function for the deleter function, then that function is not included in the interface and users cannot call the function from MATLAB. The MATLAB user calls the MATLAB delete function, which calls the function specified by 'DeleteFcn'.

For more information, see Pass Ownership of Memory to MATLAB.

Example: 'DeleteFcn','objFree'

Version History

Introduced in R2019a