defineArgument

Class: clibgen.ConstructorDefinition
Namespace: clibgen

Add input argument definition for C++ constructor

Syntax

defineArgument(ConstructorDefinition,CPPName,MATLABType)

defineArgument(ConstructorDefinition,CPPName,MATLABType,Direction)

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

defineArgument(___,Name,Value)

Description

defineArgument(ConstructorDefinition,CPPName,MATLABType) adds an input argument definition for a C++ constructor.

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

defineArgument(ConstructorDefinition,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

ConstructorDefinition — Constructor definition

clibgen.ConstructorDefinition

Constructor definition, specified as a clibgen.ConstructorDefinition object.

CPPName — C++ argument name

string scalar | character vector

C++ argument name, specified as a string scalar or a character vector and is used with the 'Description' name-value pair argument.

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 — Information for defining data dimensions

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

Since R2020a

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

Version History

Introduced in R2019a