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.
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);endfunction out = local(args)arguments args.xendout = 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);endfunction out = local(args)arguments args.xendout = 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 likelycaused 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: 17Code 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.
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 thearguments
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:
Empty Repeating Input Argument
Passing Input Argument Name at Run Time
Output Argument Validation of Conditionally-Assigned Outputs
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 command or accelerate fixed-point code by using the fiaccel (Fixed-Point Designer) 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 = 7endout = a + b + c;end |
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 = 7endout = a + b + c;end |
codegen -config:lib -c useDefaults_2 -args 0 -report Generated code: double useDefaults_2(double a){ return (a + 5.0) + 7.0;} |
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
arguments
Related Topics
- Function Argument Validation
- Use Function Argument Validation to Specify Entry-Point Input Types