Use Function Argument Validation to Specify Entry-Point Input Types
Unlike MATLAB®, which is a dynamically typed 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 Types of Entry-Point Function Inputs.
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:
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, mustBeSparse, mustBeNonsparse, and mustBeReal.
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:
Provide a class name in the argument declaration.
Use the validator
mustBeA
.For input that can be GPU data, use
coder.specifyAsGPU
.
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) %#codegenarguments a (1,:) double b (1,:) {mustBeA(b, "double")}endy = 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:
If you generate code at the command line by using the
codegen
command, do not pass the-args
option.If you generate code by using the MATLAB Coder app, enable Determine input types from code preconditions or validation. If you enable this parameter, the app labels all entry-point function inputs as
Deferred
and infers the input types from your MATLAB code during code generation.
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
orstruct
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.
Generates code that does not perform size or type coercion in the entry-point function. See Incompatibility with MATLAB for Size and 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 thecodegen
command.Does not support the generation of single precision C/C++ code. To generate single precision C/C++ code, use
codegen -singleC
and specify input types using-args
.
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:
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 property as complex or nonsparse data, using the validation functions
coder.mustBeComplex
,mustBeA
,mustBeSparse
,mustBeNonsparse
, andmustBeReal
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)) endend
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:
Provide a class name in the property declaration.
Use the validator
mustBeA
.
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) doubleendy = x * 2;end
multiplyVector
accepts 2-element row vectors, 2-element column vectors, and scalars because 2-element column vectors and scalars are compatible with 2-element row vectors. MATLAB also implicitly converts arrays of different types into the specified type. For example, if you pass the string array ["1" "2"] to multiplyVector
, MATLAB converts the string array to the numeric array [1 2]
and returns [2 4]
.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 (:,:) doubleendout = multiplyVector(in);endfunction y = multiplyVector(x)arguments x (1,2) doubleendy = 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
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) stringendout = 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) endend
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) %#codegenarguments fruit (1,1) FruitClass target (1,1) doubleendfruitVal = 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
See Also
arguments | assert | codegen
Related Topics
- Specify Types of Entry-Point Function Inputs
- Generate Code for arguments Block That Validates Input and Output Arguments
- Resolve Issue: Using arguments Blocks to Specify Cell or Structure Entry-Point Input Types is Not Supported
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Contact your local office