arguments

関数の引数の検証を宣言

構文

arguments
    argName1 (dimensions) class {validators} = defaultValue
    ...
    argNameN ...
end

arguments (Repeating)
    argName1 (dimensions) class {validators} = defaultValue
    ...
    argNameN ... 
end

arguments (Output)
    argName1 (dimensions) class {validators}
    ...
    argNameN ...
end

arguments (Output,Repeating)
    argName (dimensions) class {validators}
end

説明

入力引数ブロック

arguments ... end は、関数の入力引数を宣言します。arguments ブロックはオプションです。1 つ以上の arguments ブロックを含める場合は、関数の最初の実行可能行の前になければなりません。MATLAB^® は、Input または Output による明示的なラベリングがされていない任意の引数ブロックを入力ブロックとして扱います。

各引数には、次の構文に示すように 1 つ以上の制限または既定値を指定できます。

argName (dimensions) class {validators} = defaultValue

(dimensions) — 入力サイズ。(1,2)、(3,5,2)、(1,:) など、2 つ以上の数値のコンマ区切りリストとして指定します。コロンを使用すると、その次元で任意の長さが許可されます。(dimensions) に式を含めることはできません。
入力の次元は、(dimensions) と完全に一致するか、(dimensions) で指定されたサイズと "互換" しなければなりません。たとえば、(1,:) は、入力が 1 行 n 列の行ベクトルでなければならないことを指定しますが、n 行 1 列の列ベクトルが互換します。この関数は、行ベクトル入力を列ベクトルに変更します。同様に、(2,3) のサイズではスカラー入力が許可されますが、入力は 2 行 3 列の行列に展開されます。詳細については、基本的な演算で互換性のある配列サイズを参照してください。
class — クラスまたは MATLAB データ型。double などの名前として指定します。入力は指定された型、またはその型に変換できる型でなければなりません。たとえば、double を指定する関数はクラス single の値を受け入れて、それらの値を double に変換します。変換の詳細については、暗黙的なクラス変換を参照してください。
{validators} — 中かっこで囲まれた mustBeNumeric や mustBeScalarOrEmpty などの検証関数のコンマ区切りのリスト。検証関数は、入力引数がその条件と一致しない場合エラーになります。class と異なり、検証関数は入力引数を変更しません。検証関数の一覧については、引数の検証関数を参照してください。
defaultValue — 既定値は、指定されたサイズ、型、および検証ルールと一致しなければなりません。既定値は式にすることもできます。既定値を指定すると、引数はオプションになります。オプションの引数は、関数シグネチャと arguments ブロック内で必須の引数の後に配置しなければなりません。

名前と値の引数では、arg は nv.name 形式を使用します。ここで、nv は関数シグネチャの構造体名で、name は arguments ブロックの引数名です。たとえば、options という名前の構造体を使用して、名前と値の引数を受け入れる関数を定義します。

y = myFunction(x,options)

arguments ブロックで、次のように、名前と値の引数の名前をフィールドとして指定します。

arguments 
    x
    options.Name1
    options.Name2
end

一般的な arguments ブロックの使用方法の詳細については、arguments ブロック構文を参照してください。

例

arguments (Repeating) ... end は繰り返し入力引数を宣言します。

たとえば、繰り返し引数 X、Y、および style を使用して myplot という名前の関数を作成すると、myplot(x1,y1,style1,x2,y2,style2) のように、これら 3 つの引数の複数のセットが受け入れられます。MATLAB では、その引数で渡されるすべての値を含む cell 配列が作成されます。

関数には、1 つの repeating input arguments ブロックのみを含めることができます。関数に繰り返し引数および名前と値の引数をどちらも含める場合は、名前と値の引数を独自に宣言し、repeating arguments ブロックの後に arguments ブロックを分けます。

繰り返し引数での検証の使用の詳細については、繰り返し引数の検証を参照してください。

例

出力引数ブロック

arguments (Output) ... end は、関数の出力引数を宣言します。output arguments ブロックはオプションです。1 つ以上の出力 arguments ブロックを含める場合は、すべての入力ブロックの後、かつ関数の最初の実行可能行の前になければなりません。入力ブロックと出力ブロックの両方を関数に含める場合は、読みやすくするため、(Input) および (Output) 属性を明示的に含めることを推奨します。例については、引数の検証を使用する繰り返し出力を参照してください。(R2022b 以降)

入力引数と同様、出力引数には、次の構文に示すように 1 つ以上の制限を指定できます。

argName (dimensions) class {validators}

詳細は、arguments ... end の説明を参照してください。入力引数とは異なり、出力引数には既定値を定義できません。また、ある出力引数に適用された検証関数は、それより前の出力引数を参照できません。

例

arguments (Output,Repeating) ... end は、関数の繰り返し出力引数を宣言します。繰り返し出力引数に対する引数の検証を使用できますが、関数ごとに定義できる繰り返し出力引数は 1 つのみです。varargout は、それが唯一の出力引数であれば、repeating output arguments ブロックで使用できます。(R2022b 以降)

例

すべて折りたたむ

入力のサイズと型の制限

入力引数のサイズを、任意の長さの行ベクトルに制限する関数を記述します。検証関数を使用して、そのベクトルの要素を数値に制限します。

function [m,s] = twoStats(x)
    arguments
        x (1,:) {mustBeNumeric}
    end
    m = mean(x,"all");
    s = std(x,1,"all");
end

関数を 3 つの要素の行ベクトルで呼び出します。

a = [1 3 5];
[m,s] = twoStats(a)

行ベクトルと列ベクトルは互換するため、列ベクトルを指定して関数を呼び出すこともできます。

a = [1 3 5]';
[m,s] = twoStats(a)

非数値を含むベクトルを指定して関数を呼び出すと、検証関数 mustBeNumeric はエラーをスローします。

a = ["1" "3" "5"];
[m,s] = twoStats(a)

Error using twoStats
Invalid argument at position 1. Value must be numeric.

名前と値の引数の定義

関数のオプションの名前と値の引数を宣言するには、関数宣言に構造体名を含めて、引数名を arguments ブロックのその構造体のフィールドとして定義します。

構造体名として options をもつ関数 myRectangle を宣言します。options、LineStyle および LineWidth の 2 つのフィールドは、関数の名前と値の引数の名前です。

function myRectangle(X,Y,options)
    arguments
       X double
       Y double
       options.LineStyle (1,1) string = "-" 
       options.LineWidth (1,1) {mustBeNumeric} = 1
    end
    % Function code
    ...
end

どちらの引数名にも既定値が定義されているため、両方ともオプションです。以下の構文はすべて、関数を呼び出す有効な方法です。

myRectangle(4,5)
myRectangle(4,5,LineStyle=":",LineWidth=2)
myRectangle(4,5,LineWidth=2,LineStyle=":")
myRectangle(4,5,LineStyle=":")
myRectangle(4,5,LineWidth=2)

R2021a より前は、string または文字ベクトルとして名前を渡し、名前と値をコンマで区切ります。両方の構文は以降のリリースでも有効です。

繰り返し入力引数の定義

繰り返し引数は、関数呼び出しで 0 回以上繰り返すことのできる単一の引数または引数のグループです。関数 fRepeat は、引数 x、y、および style の繰り返しグループを受け入れます。入力引数 x および y を double 値のベクトルまたは double に変換可能な値に制限します。style を string "--" と ":" に制限します。

function fRepeat(x,y,style)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
        style {mustBeMember(style,["--",":"])}       
    end
    
    % Reshape the cell arrays of inputs and call plot function
    z = reshape([x;y;style],1,[]);
    if ~isempty(z)
        plot(z{:});
    end
end

2 つの入力グループを指定して fRepeat を呼び出します。MATLAB では、x で渡されるすべての値を含む cell 配列、y の値の別の配列、および style の値の 3 つ目の配列が作成されます。これらの配列は 1 行 6 列の cell 配列 z に変更されて、plot に渡されます。

x1 = 1:10;
y1 = 1:10; 
s1 = ":"; 
x2 = 1:7;
y2 = 1:1.5:10;
s2 = "--";
fRepeat(x1,y1,s1,x2,y2,s2)

Plot showing two lines

引数の検証による出力値の制限

2 次元の正方形パッチを、点 (0.4, 0.4) を中心にユーザーが指定した角度で回転させる関数を作成します。最終イメージの x 座標と y 座標を出力引数として返し、その値が正になるよう制限します。つまり、この関数は回転の最終結果が完全に第 1 象限に入る場合のみ座標を返します。

function [xfinal,yfinal] = rotatePatch(angle)
    arguments (Output)
        xfinal {mustBePositive}
        yfinal {mustBePositive}
    end
    x = [0.1 0.1 0.7 0.7];
    y = [0.1 0.7 0.7 0.1];
    p = patch(x,y,"red");
    rotate(p,[0 0 1],angle,[0.4 0.4 0])
    xfinal = p.Vertices(:,1);
    yfinal = p.Vertices(:,2);
end

角度を 15 度に指定してこの関数を呼び出します。この回転ではどの頂点も第 1 象限の外には出ないため、この関数ではエラーは返されません。

[x1,y1] = rotatePatch(15)

Plot of red square rotated counterclockwise 15 degrees

角度を 35 度に指定してこの関数を呼び出します。すると、左下の頂点が第 1 象限の外に出ます。x 座標が負になり、出力引数の検証を満たさないため、この関数はエラーを返します。

[x2,y2] = rotatePatch(35)

Invalid output 'xfinal'. Value must be positive.

Error in rotatePatch (line 12)
end

Plot of two red squares rotated counterclockwise 15 and 35 degrees

引数の検証を使用する繰り返し出力

ベクトルのペアの繰り返しを受け入れて、各ペアの和を返す関数を作成します。入力および出力を行ベクトルに制限します。

function vectorSum = repeatSum(a,b)
  arguments (Input,Repeating)
    a (1,:)
    b (1,:)
  end
  arguments (Output,Repeating)
    vectorSum (1,:)
  end

  n = numel(a);
  vectorSum{n} = a{n} + b{n};
  for i = 1:n-1
    vectorSum{i} = a{i} + b{i};
  end
end

最終出力を計算し、for ループの前に vectorSum{n} に代入すると、cell 配列のスペースが事前に割り当てられます。事前の割り当てをしないでループ内で cell 配列を拡張すると、パフォーマンスが低下する場合があります。

ベクトルのペアを 2 組定義します。この 2 組のペアを入力として repeatSum を呼び出します。列ベクトルと行ベクトルのサイズに互換性があるため、input arguments ブロックの検証により列ベクトルが行ベクトルに変換されます。

x1 = [1 2];
y1 = [3 4];
x2 = [1; 0];
y2 = [0; 1];
[sum1,sum2] = repeatSum(x1,y1,x2,y2)

入力は行ベクトルに制限されているため、ベクトルの各ペアの和は必ず行ベクトルになります。しかし、出力検証により、この関数が後で修正された場合でも確実に行ベクトルを生成するようにできます。たとえば、入力検証が関数 mustBeVector に変更された場合、ペアは変換されていない 1 つの行ベクトルと 1 つの列ベクトルで構成されることがあります。その場合、x1 と y2 の和は行列です。

x1 + y2

修正された repeatSum では、この行列が出力検証に合格しないため、出力はエラーとなります。

制限

引数ブロックは入れ子関数、抽象メソッド、またはハンドルクラスのデストラクターメソッドではサポートされません。

詳細

すべて折りたたむ

サポートされているデータ型

引数の宣言では、Java クラス、COM クラス、および MATLAB ソフトウェア Version 7.6 より前に定義された MATLAB クラス (classdef キーワードを使用しないクラス定義) を除く、任意の MATLAB クラス、または MATLAB でサポートされている外部定義クラスを指定できます。

ヒント

データ型制限を使用すると、入力引数の暗黙の変換が行われます。以下に例を示します。
```
function y = myFunction(inputArg1)
    arguments
        inputArg1 (1,1) double
    end
    ...
```
この関数では、string "123" を入力引数として渡すと、MATLAB で string が double 型の数値 123 に変換されます。
検証関数では入力値は変更されないため、データ型の変換を回避するには、入力を制限するデータ型ではなく、1 つ以上の検証関数を使用します。以下に例を示します。
- string から数値への変換を回避するには、mustBeA、mustBeFloat、または mustBeNumeric を使用します。
- 数値から string への変換を回避するには、mustBeText、mustBeTextScalar、または mustBeNonZeroLengthText を使用します。
- サイズ変換を回避するには、mustBeVector または mustBeScalarOrEmpty を使用します。
MATLAB では、arguments ブロックを含む関数のコードの補完と候補を、arguments ブロックに含まれている情報に基づいて提供できます。この情報は、functionSignatures.json ファイルがなくても使用できます。コードの候補と補完のカスタマイズの詳細については、コードの候補と補完のカスタマイズを参照してください。

拡張機能

C/C++ コード生成
MATLAB® Coder™ を使用して C および C++ コードを生成します。

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

コード生成では、arguments ブロックの以下の機能はサポートされていません。

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

コード生成の追加の考慮事項については、入力引数と出力引数を検証する arguments ブロックのコード生成 (MATLAB Coder)を参照してください。arguments ブロックを使用してエントリポイント関数への入力引数の型を指定する場合は、さらに考慮事項が適用されます。Use Function Argument Validation to Specify Entry-Point Input Types (MATLAB Coder)を参照してください。