Use Argument and Property Validation to Specify Entry-Point Input Types

Unlike MATLAB^®, which is an untyped language, C and C++ are statically typed. Therefore, to generate C/C++ code, you must specify the types of the input variables to the MATLAB entry-point function. The code generator uses these specifications to infer the types of all variables in the generated code. One of the ways to specify input types is by using function argument validation (arguments blocks) in your MATLAB code. Alternatively, you can specify input types by using the codegen command with -args at the command line, by using the MATLAB Coder™ app, or by using assert statements in your MATLAB code. For an overview of these methods of input type specification, see Specify Properties of Entry-Point Function Inputs.

Specifying 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 argument and property validation supports:

Numeric, logical, half, character, string, and enumeration data types
User-written MATLAB classes that contain property validation
Fixed-size and unbounded variable-size dimensions specified using colons (:)
Special attributes, including specifying the input as complex, sparse, or GPU data, using the validation functions coder.mustBeComplex, coder.specifyAsGPU, mustBeA, mustBeNonsparse, mustBeReal, and mustBeSparse

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.

function y = myMultiply(a,b) %#codegen
arguments
    a (1,:) double
    b (1,:) 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.

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:

Your MATLAB code already performs function argument validation using arguments blocks.
You want to keep input-type specification with the entry-point function.
You need to generate only one function signature.
You do not need to specify bounded variable-size input arguments.
You can convert cell or struct input arguments to your entry-point function into classes. See Resolve Issue: Using arguments Blocks to Specify Cell or Structure Entry-Point Input Types is Not Supported.
Your entry-point inputs include user-written classes with property validation.
You do not need to use coder.OutputType objects to specify input types.

Advantages of Input-Type Specification Using Function Argument Validation

Input-type specification using function argument validation:

Allows you to specify the aspects of arguments that are required for code generation in a dedicated code block
Results in clearer and more concise MATLAB code, as compared to input-type specification using preconditioning (assert statements)
Simplifies code generation, because you don’t have to specify input types each time you generate code in the MATLAB Coder app or at the command line
Documents argument specifications in the MATLAB entry-point function

Limitations of Input-Type Specification Using Function Argument Validation

Input-type specification using function argument validation:

Does not support certain input types, including cells and structures. For a workaround, see Resolve Issue: Using arguments Blocks to Specify Cell or Structure Entry-Point Input Types is Not Supported.
Produces MEX files that do not perform size or type coercion.
Ignores default values in the entry-point function; calls to the generated MEX or C/C++ functions must include all arguments you define in the arguments block.
Can be preempted using codegen with the -args argument.
Might exhibit undefined behavior if you override default validator functions.
Does not support the -float2fixed option with the codegen command.

Examples

Use the `arguments` Block to Specify String and Character Vector Input

Write a function that concatenates a character vector and a string scalar to form a string scalar. Use the arguments block to specify the argument charVec as an unbounded character vector and the argument strScalar as a string scalar.

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

Generate C/C++ code for this function at the command line without further specification of input types.

codegen myString

Code generation successful.

Confirm that the generated MEX file produces the expected output.

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

joinedString = 

    "hello world"

Use `arguments` Block to Specify Enumeration Input

Create an enumeration class for selected fruits, with values corresponding to the milligrams of vitamin C per serving:

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

Write a function that, given a FruitClass input and a target value representing milligrams of vitamin C, returns the number of servings of fruit that you must eat to achieve the target.

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

Generate code for the calculateIntake function at the command line without further specification of input types.

codegen calculateIntake;

Code generation successful.

Confirm that the generated MEX file produces the expected output.

servings = calculateIntake_mex(FruitClass.Strawberry,1000);

servings =

   20.4082