入力引数と出力引数を検証する arguments ブロックのコード生成

入力引数と出力引数を検証する `arguments` ブロックのコード生成

MATLAB^® 関数で入力引数と出力引数の検証を実行する arguments ブロックのコードを生成できます。引数の検証を使用すると、関数の入力値と出力値のクラス、サイズ、および他の特性を制約でき、これらのテストを実行するコードを関数本体に記述する必要がありません。関数の引数の検証を参照してください。

Pseudocode snippet demonstrating the syntax of the arguments block

サポート機能

コード生成では、サイズとクラスの検証、検証関数、既定値を含む arguments ブロックのほとんどの機能がサポートされます。コード生成では、関数 namedargs2cell もサポートされます。

コード生成は、arguments ブロックの次の機能をサポートしません。

繰り返し引数のサイズの検証、クラスの検証、および検証関数
複数の繰り返し入力引数
エントリポイント関数での名前と値の入力引数
structName.?ClassName 構文を使用したクラスプロパティからの名前と値の入力引数
table、timetable、または dlarray (Deep Learning Toolbox) オブジェクトのサイズの検証。

名前はコンパイル時の定数でなければならない

関数 foo で名前と値の引数の検証を使用するとします。foo を別の関数 bar から呼び出す場合、コンパイル時に foo に指定する名前をコードジェネレーターで特定できなければなりません。

たとえば、エントリポイント関数 myNamedArg_valid のコード生成は成功します。この関数には、関数 local の呼び出しが 2 つ含まれています。これらの両方の呼び出しでは、引数の名前 'x' がコード生成時にわかっています。

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.

一方、エントリポイント関数 myNamedArg_invalid のコード生成は、関数 local の引数の名前が実行時に提供されないため失敗します。

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

特定の状況では、オプションの位置入力引数または繰り返し入力引数に渡した名前がコードジェネレーターで代入されます。このような状況では、コード生成は成功しますが警告が発生し、生成コードと MATLAB の実行で異なる結果になることがあります。実行時の入力引数名の引き渡しを参照してください。

名前と値の引数を保持する構造体の使用

コード生成の対象となる MATLAB 関数で、NameValueArgs という名前の構造体を使用して 2 つの名前と値の引数 Name1 と Name2 が定義されているとします。

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

データの読み取りと書き込みには、構造体フィールド NameValueArgs.Name1 と NameValueArgs.Name2 を関数の本体で直接使用します。

次の状況を除き、構造体変数 NameValueArgs 自体を全体として (ドット構文なしで) 使用しないでください。

関数 isfield を使用して、特定の名前と値の引数の値が呼び出し元で提供されているかどうかを確認する。たとえば、NameValueArgs.Name2 の既定値を arguments ブロックの外で提供するには、次のコードの抜粋を使用できます。
```
if ~isfield(NameValueArgs,'Name2')
    NameValueArgs.Name2 = defaultValue;
end
```
関数 namedargs2cell を使用して、名前と値の引数を別の関数に転送する。次に例を示します。
```
argsCell = namedargs2cell(NameValueArgs);
foo(argsCell{:});
```

構造体変数 NameValueArgs 全体の使用 (上記の 2 つの特殊なケースを含む) は、ループ、無名関数、入れ子関数の内部ではサポートされません。

生成されたコードと MATLAB コードの相違点

通常と異なる特定のコードパターンにより、引数の検証用に生成されるコードが MATLAB と異なる動作になることがあります。それらのいくつかの違いの詳細については、次のリンクを参照してください。

生成コード内のエントリポイント関数の入力の既定値

arguments ブロックを使用すると、1 つ以上の位置入力引数の既定値を指定できます。引数の宣言で既定値を指定すると、関数呼び出しで値を渡さない場合に MATLAB で既定値を使用できるため、位置引数はオプションになります。codegen コマンドを使用してコードを生成する場合や fiaccel (Fixed-Point Designer) コマンドを使用して固定小数点コードを高速化する場合に、一定の既定値をもつ 1 つ以上のオプションの位置引数について、そのプロパティを指定しないように選択できます。このような場合、それらのオプションの引数の既定値が生成コードにハードコードされ、それらの引数は生成コードのインターフェイスに表示されません。例については、次の表を参照してください。

MATLAB コード	生成コード
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` コマンド: codegen -config:lib -c useDefaults_1 -args {} -report 生成コード: 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` コマンド: codegen -config:lib -c useDefaults_2 -args 0 -report 生成コード: double useDefaults_2(double a) { return (a + 5.0) + 7.0; }
`codegen` コマンド: codegen -config:lib -c useDefaults_2 -args {0,0} -report 生成コード: double useDefaults_2(double a, double b) { return (a + b) + 7.0; }

MATLAB コード

生成コード

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 コマンド:

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

生成コード:

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 コマンド:

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

生成コード:

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

codegen コマンド:

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

生成コード:

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

入力の型の指定と `arguments` ブロック

いくつかの制限はありますが、MATLAB エントリポイント関数で arguments ブロックを使用して、コード生成用に入力の型を指定できます。Use Function Argument Validation to Specify Entry-Point Input Typesを参照してください。

参考

arguments

サポート機能

名前はコンパイル時の定数でなければならない

名前と値の引数を保持する構造体の使用

生成されたコードと MATLAB コードの相違点

生成コード内のエントリポイント関数の入力の既定値

入力の型の指定と arguments ブロック

参考

関連するトピック

入力引数と出力引数を検証する `arguments` ブロックのコード生成

入力の型の指定と `arguments` ブロック