Specify Input Types Using arguments Blocks

You can specify the class, size, and other aspects of input variables in your entry-point MATLAB function by using arguments blocks to perform function argument validation.

Specifying input types using arguments blocks supports:

Input type specification using arguments blocks requires explicit specification of input argument size and class. Specify argument size in the argument declaration. To specify argument class, use one of these methods:

For example, construct an entry-point MATLAB function myMultiply, which returns the product of two input arguments, a and b. Use an arguments block to declare that a and b are unbounded row vectors of real double values. Specify the sizes of a and b in the argument declaration. Specify the class of a in the argument declaration and specify the class of b using the mustBeA validator

function y = myMultiply(a,b) %#codegen
arguments
    a (1,:) double
    b (1,:) {mustBeA(b, "double")}
end
y = a*b;
end

At the MATLAB command line, run this codegen command.

codegen myMultiply

The code generator uses the arguments block to assign types to all variables in the myMultiply function, without further input-type specification.

Instruct the Code Generator to Use arguments Block for Input-Type Specification

To instruct the code generator to determine input types using the arguments block, use one of these approaches:

When to Use arguments Blocks for Input-Type Specification

Consider using arguments blocks for input-type specification when one or more of these statements are true:

Use User-Written MATLAB Classes in arguments Blocks

Suppose that one of your entry-point input arguments is an instance of MyClass, a MATLAB class that you wrote. If you use function argument validation (an arguments block) to specify input types, you must also use property validation (a properties block) to specify the types of all properties of MyClass.

For user-written MATLAB class inputs specified using function argument validation, property validation supports:

To specify that a property contains sparse data by using the validator mustBeSparse, explicitly assign a default sparse value to the property. This value is ignored during input-type specification, but is required to correctly create the property in the generated code. For example, create class MyClass and specify that MyClass property prop contains sparse data. Explicitly assign prop a default sparse value.

classdef MyClass
    properties
        prop (1024,1024) double {mustBeSparse} = sparse(zeros(1024,1024))
    end
end

Input type specification for user-written MATLAB classes using properties blocks requires explicit specification of property size and class. Specify property size in the property declaration. To specify property class, use one of these methods:

Code generation does not support property validation using coder.specifyAsGPU for user-written MATLAB class inputs specified using an arguments block.

Incompatibility with MATLAB for Size and Type Coercion

In MATLAB execution, the arguments block performs size and type coercion. This means that the arguments block accepts all inputs that are compatible with or convertible to the sizes and types specified in the argument declaration. See Compatible Array Sizes for Basic Operations and Implicit Class Conversion.

For example, create the function multiplyVector. Use an arguments block to specify that input variable x is a 2-element row vector of doubles.

function y = multiplyVector(x)
arguments
    x (1,2) double
end
y = x * 2;
end

However, when you generate code for the entry-point function multiplyVector, the generated code performs neither size nor type coercion on the value passed to the entry-point function. For example, if you generate a MEX function from multiplyVector, the generated MEX function multiplyVector_mex will accept only a 2-element row vector of doubles. If you pass multiplyVector_mex a 2-element column vector or a scalar, the MEX function will produce a run-time error. If you pass multiplyVector_mex a vector containing values that are not doubles, the MEX function will produce a run-time error.

To work around this limitation and generate code that performs size coercion on input values, construct a wrapper entry-point function that calls your original entry-point function. Construct the wrapper function such that it accepts all inputs that are compatible with the size specified in your original entry-point function. The original entry-point function now performs coercion on the input values. This workaround succeeds because arguments blocks that are not in entry-point functions do perform size and type coercion in the generated code. For example, create the function wrapper, which calls the original entry-point function multiplyVector, and generate code for wrapper. The generated MEX function wrapper_mex accepts 2-element row vectors, 2-element column vectors, and scalars.

function out = wrapper(in)
arguments
    in (:,:) double
end
out = multiplyVector(in);
end

function y = multiplyVector(x)
arguments
    x (1,2) double
end
y = x * 2;
end

To perform both size and type coercion, you cannot use an arguments block to specify entry-point function input types. Instead, you must use the codegen function with -args to generate code that supports multiple signatures. See Generate Code for Functions with Multiple Signatures.

Examples

function out = myString(charVec, strScalar)
arguments
    charVec (1,:) char
    strScalar (1,1) string
end
out = charVec + strScalar;
end

codegen myString

Code generation successful.

joinedString = myString_mex('hello ',"world")

joinedString = 

    "hello world"

classdef FruitClass < uint32
    enumeration
        Orange      (70)
        Kiwi        (64)
        Strawberry  (49)
        Grapefruit  (39)
        Cantalope   (29)
        Tomato      (17)
        Pepper      (95)
    end
end

function out = calculateIntake(fruit, target) %#codegen
arguments
    fruit (1,1) FruitClass
    target (1,1) double
end
fruitVal = double(fruit);
out = target/fruitVal;
end

codegen calculateIntake;

Code generation successful.

servings = calculateIntake_mex(FruitClass.Strawberry,1000);

servings =

   20.4082