defineOutput

R2026b

Class: clibgen.FunctionDefinition
Namespace: clibgen

(Not recommended) Add output argument definition for C++ package function

defineOutput is not recommended. For more information on updating your code, see Version History.

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.

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 Size Property.

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 Size
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'

Examples

Add deleteFcn

Specify the function ptFree as a deleter function.

The library header file defines functions ptCreate and ptFree.

PT *ptCreate(int32  width, int32  height, int32  depth); 
void ptFree(PT *pt); 

Edit the library definition file to include the DeleteFcn argument.

defineOutput(ptCreateDefinition, 'RetVal', 'clib.libName.PT', 1, 'DeleteFcn', 'ptFree'); 

In MATLAB, create a PT object.

ptObj = clib.libName.ptCreate(w, h, d);

Call delete on the object. MATLAB calls the C++ function ptFree on the underlying C++ object.

delete(ptObj);

Version History

Introduced in R2019a

R2026b: Not recommended

There are no plans to remove defineOutput. However, creating a clibgen.api.InterfaceDefinition object in the clibgen.api namespace is recommended instead.