Main Content

Generate Code for arguments Block That Validates Input and Output Arguments

You can generate code for arguments blocks that perform input and output argument validation in your MATLAB® function. Using argument validation, you can constrain the class, size, and other aspects of function input and output values without writing code in the body of the function to perform these tests. See Function Argument Validation.

If you validate function input arguments using an arguments block in your MATLAB entry-point function, you can also use the arguments block to specify the input types for code generation, with certain restrictions. See Use Function Argument Validation to Specify Entry-Point Input Types (MATLAB Coder).

Pseudocode snippet demonstrating the syntax of the arguments block

Supported Features

Code generation supports most features of arguments blocks, including size and class validation, validation functions, and default values. Code generation also supports the namedargs2cell function.

Code generation does not support these features of arguments blocks:

  • Size validation, class validation, and validation functions for repeating arguments

  • Multiple repeating input arguments

  • Name-value input arguments at entry-point functions

  • Size validation for table or timetable objects.

Names Must Be Compile-Time Constants

Suppose that foo is a function that uses name-value argument validation. When you call foo from another function bar, the code generator must be able to determine the names that you provide to foo at compile time.

For example, code generation succeeds for the entry-point function myNamedArg_valid. This function contains two calls to the function local. For both these calls, the argument name 'x' is known during code generation.

function [out1,out2] = myNamedArg_valid(in1,in2)
out1 = local(x=in1);
out2 = local('x',in2);
end

function out = local(args)
arguments
    args.x
end

out = args.x;
end
codegen myNamedArg_valid -args {0,0}
Code generation successful.

By contrast, code generation fails for the entry-point function myNamedArg_invalid because the argument name for the function local is supplied at run time.

function out = myNamedArg_invalid(value, inputName)
out = local(inputName, value);
end

function out = local(args)
arguments
    args.x
end

out = args.x;
end
codegen myNamedArg_invalid -args {0,coder.typeof('a')}
Error calling 'myNamedArg_invalid/local'. This call-site passes more inputs to this function than it can accept. This is likely
caused by: This argument is not constant, and therefore does not match against a name-value argument inside
'myNamedArg_invalid/local' during code generation. Code generation might fail or produce results that do not agree with MATLAB 
if a name passed at a call site is not known during code generation.

Error in ==> myNamedArg_invalid Line: 2 Column: 17
Code generation failed: View Error Report

In certain situations, the code generator assigns the name that you passed to an optional positional or repeating input argument. In such situations, code generation succeeds with a warning and the generated code might produce results that are different from MATLAB execution. See Passing Input Argument Name at Run Time (MATLAB Coder).

Using the Structure That Holds Name-Value Arguments

Suppose that your MATLAB function for which you intend to generate code uses a structure named NameValueArgs to define two name-value arguments, Name1 and Name2:

function result = myFunction(NameValueArgs)
    arguments
        NameValueArgs.Name1
        NameValueArgs.Name2
    end
    ...
end

In the body of your function, directly use the structure fields NameValueArgs.Name1 and NameValueArgs.Name2 to read or write data.

Do not use the whole structure variable NameValueArgs itself (without the dot syntax), except in these situations:

  • Use the isfield function to check if the caller has supplied a value for a certain name-value argument. For example, to provide a default value for NameValueArgs.Name2 outside of the arguments block, you can use this code snippet:

    if ~isfield(NameValueArgs,'Name2')
    NameValueArgs.Name2 = defaultValue;
end

  • Use the namedargs2cell function to forward the name-value arguments to another function. For example:

    argsCell = namedargs2cell(NameValueArgs);
foo(argsCell{:});

Use of the whole structure variable NameValueArgs (including the above two special cases) is not supported inside loops, anonymous functions, or nested functions.

Differences Between Generated Code and MATLAB Code

Certain unusual code patterns might cause the code generated for argument validation to behave differently from MATLAB. To learn about some of these differences, see these links:

Default Values for Entry-Point Function Inputs in Generated Code

The arguments block allows you to specify default values for one or more positional input arguments. Specifying a default value in the argument declaration makes a positional argument optional because MATLAB can use the default value when you do not pass a value in the function call. When you generate code by using the codegen (MATLAB Coder) command or accelerate fixed-point code by using the fiaccel command, you can choose to not specify the properties of one or more optional positional arguments that have constant default values. In such situations, the default values of these optional arguments are hard-coded in the generated code and these arguments do not appear in the generated code interface. For examples, see the following table.

MATLAB Code

Generated Code

function out = useDefaults_1(a,b,c)
arguments
    a (1,1) double = 3
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen command:

codegen -config:lib -c useDefaults_1 -args {} -report

Generated code:

double useDefaults_1(void)
{
  return 15.0;
}

function out = useDefaults_2(a,b,c)
arguments
    a (1,1) double
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen command:

codegen -config:lib -c useDefaults_2 -args 0 -report

Generated code:

double useDefaults_2(double a)
{
  return (a + 5.0) + 7.0;
}

codegen command:

codegen -config:lib -c useDefaults_2 -args {0,0} -report

Generated code:

double useDefaults_2(double a, double b)
{
  return (a + b) + 7.0;
}

See Also

Related Topics