define

R2026b

Define input argument in C++ library function or method

Since R2026b

collapse all in page

    Syntax

    define(inargDef,Name=Value)

    Description

    define(inargDef,Name=Value) defines or customizes an input 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 argument as a null-terminated C string, set MATLABType to "string" and Size to "nullTerminated".

    The documentation for this function setName defines the input as a null-terminated C string.

    void setName(char const * name);

    Publish an interface libname containing setName. The status of the function is Incomplete.

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

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

  Show all properties

    Display information about the input argument. The MATLABType and Size properties are undefined.

    fcn.CPPInputs
    ans = 
  InputArgumentDefinition with properties:

          Name: "name"
      Position: 1
       CPPType: "char const *"
    MATLABType: <undefined>
     Direction: input
          Size: <undefined>
        Status: Incomplete

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

    arg = fcn.CPPInputs;
define(arg,MATLABType="string",Size="nullTerminated")
fcn

    fcn = 
  FunctionDefinition with properties:

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

  Show all properties

    The setName function is now included in the interface.

    In MATLAB, call clib.libname.setName with a string input argument.

    fcn.MATLABSignature
    ans = 
    "MATLAB signature for FunctionDefinition
     	Maps C++ signature:
     	void setName(char const * name)
     
     	to MATLAB as:
     	clib.libname.setName(name)
     		Input Arguments
     			name  string
     "

    For example:

    clib.libname.setName("NewName")

    Input Arguments

    collapse all

    Input argument definition, specified as a clibgen.api.InputArgumentDefinition 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(inArg,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.

    How the argument is used, specified as "input", "output", or "inputoutput".

    Dimensions of the 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 MATLAB data allowed as input to a C++ pointer argument. For example:

    • If Size = 1, only inputs with one element are allowed.

    • If Size = 5, only an input vector with five elements is allowed.

    • If Size = "len", an input vector with any number of elements is allowed. MATLAB determines the actual number of elements from the inputs when calling the function and passes it to the C++ function using the "len" parameter.

    • If Size = ["m","n"], only a 2-D matrix input is allowed, but any number of elements are allowed for each dimension. MATLAB determines the actual number of elements from the inputs when calling the function and is passes them to the C++ function using the "m" and "n" parameters.

    • If Size = "nullTerminated", only a MATLAB string is allowed.

    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 must 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.

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

    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 Size argument. To insert singleton dimensions at the end, set AddTrailingSingletons to true. For more information, see Dimension Matching.

    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. When the MATLABType is "string" and the Direction is "output", use NumElementsInBuffer. 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 *

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

    Version History

    Introduced in R2026b

    See Also

    Objects

    Topics