define

R2026b

Define output argument in C++ library function or method

Since R2026b

collapse all in page

    Syntax

    define(outargDef,Name=Value)

    Description

    define(outargDef,Name=Value) defines or customizes an output argument with one or more name-value arguments.

    example

    Examples

    collapse all

    MATLAB cannot determine whether a char const* parameter represents a text string or a character buffer. To define an output argument as a null-terminated C string, set MATLABType to "string" and Size to "nullTerminated".

    The documentation for this function getMessage specifies the output argument as a null-terminated C string.

    const char* getMessage();

    Publish an interface libname containing getMessage. The function has no input arguments and one output argument. The status of the function is Incomplete.

    fcn = idef.findFunction("getMessage")
    fcn = 
  FunctionDefinition with properties:

            CPPName: "getMessage"
         MATLABName: "clib.libname.getMessage"
         Overloaded: false
       CPPSignature: "char const * getMessage()"
    MATLABSignature: <Define incomplete output to see the MATLAB signature.>
          CPPInputs: [1×0 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×1 clibgen.api.OutputArgumentDefinition]
             Status: Incomplete
           Included: false

  Show all properties

    Display information about the output argument.

    fcn.CPPOutput
    ans = 
  OutputArgumentDefinition with properties:

          Name: "RetVal"
       CPPType: "char const *"
    MATLABType: <undefined>
          Size: <undefined>
        Status: Incomplete

    To define RetVal as a null-terminated C string, set MATLABType to "string" and Size to "nullTerminated".

    arg = fcn.CPPOutput;
define(arg,MATLABType="string",Size="nullTerminated",Description="Message returned by the library")
fcn

    fcn = 
  FunctionDefinition with properties:

            CPPName: "getMessage"
         MATLABName: "clib.libname.getMessage"
         Overloaded: false
       CPPSignature: "char const * getMessage()"
    MATLABSignature: RetVal = clib.libname.getMessage()
          CPPInputs: [1×0 clibgen.api.InputArgumentDefinition]
          CPPOutput: [1×1 clibgen.api.OutputArgumentDefinition]
             Status: Complete
           Included: true

  Show all properties

    The getMessage function is now included in the interface.

    In MATLAB, call clib.libname.getMessage.

    fcn.MATLABSignature
    ans = 
    "MATLAB signature for FunctionDefinition
     	Maps C++ signature:
     	char const * getMessage()
     
     	to MATLAB as:
     	RetVal = clib.libname.getMessage()
     		Output Arguments
     			RetVal  string
     "

    For example:

    msg = clib.libname.getMessage

    Input Arguments

    collapse all

    Argument definition, specified as a clibgen.api.OutputArgumentDefinition object.

    Name-Value Arguments

    collapse all

    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.

    Example: define(outArg,MATLABType="string",Size="nullTerminated")

    MATLAB® type for argument, specified as a string scalar.

    Use "struct" for data types that satisfy the requirements described in Supported struct Types.

    Dimensions of array data, specified as a numeric vector, string vector, cell array, or "nullTerminated". MATLAB uses this value to determine the number of elements in the pointer data returned from the function. For example:

    • Size = 1, the pointer refers to a single element.

    • Size = 5, the pointer refers to an array of five elements.

    • Size = "len", the number of elements in the array equals the value of the parameter "len".

    • Size = ["m","n"], the pointer refers to a matrix with the number of elements in each dimension equal to the values of the parameters "m" and "n".

    • Size = "nullTerminated", the pointer refers to a C++ string.

    Argument description that describes the output argument for the end user, specified as a string scalar.

    Version History

    Introduced in R2026b

    See Also

    Objects