defineOutput

Class: clibgen.FunctionDefinition
Namespace: clibgen

Add output argument definition for C++ package function

Syntax

defineOutput(funcDef,argName,mltype)
defineOutput(funcDef,argName,mltype,shape)
defineOutput(___,argDesc)
defineOutput(___,'DeleteFcn',deleteFcn)


Description

defineOutput(funcDef,argName,mltype) adds an output argument definition for a C++ package function.

defineOutput(funcDef,argName,mltype,shape) provides information about data dimensions.

defineOutput(___,argDesc) adds an argument description, and can include any of the input arguments in previous syntaxes.

defineOutput(___,'DeleteFcn',deleteFcn) specifies a C++ library deleter function to manage the memory of the argument.

Input Arguments

funcDef — Function definition

clibgen.FunctionDefinition

Function definition, specified as a clibgen.FunctionDefinition object.

argName — C++ output argument name

"RetVal" (default) | string scalar | character vector

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

mltype — 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.

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.

argDesc — C++ argument description

string scalar | character vector

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

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. If the C++ return type is void*, then deleteFcn must be a user-defined function. If the function returns a pointer, then MATLAB takes ownership and manages the life cycle 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.

Example: 'DeleteFcn','objFree'

Version History

Introduced in R2019a