arguments
関数の引数の検証を宣言
構文
arguments
argName1 (dimensions) class {validators} = defaultValue
...
argNameN ...
end
arguments (Repeating)
argName1 (dimensions) class {validators}
...
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 列の行列に展開されます。詳細については、サイズおよびクラスの検証を参照してください。classdoubleなどの名前として指定します。入力は指定された型、またはその型に変換できる型でなければなりません。たとえば、doubleを指定する関数はクラスsingleの値を受け入れて、それらの値をdoubleに変換します。変換の詳細については、暗黙的なクラス変換を参照してください。{validators}mustBeNumericやmustBeScalarOrEmptyなどの検証関数のコンマ区切りのリスト。検証関数は、入力引数がその条件と一致しない場合エラーになります。classdefaultValueargumentsブロック内で必須の引数の後に配置しなければなりません。
名前と値の引数では、argnv.namenvnameoptions という名前の構造体を使用して、名前と値の引数を受け入れる関数を定義します。
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)
m =
3
s =
1.6330行ベクトルと列ベクトルは互換するため、列ベクトルを指定して関数を呼び出すこともできます。
a = [1 3 5]'; [m,s] = twoStats(a)
m =
3
s =
1.6330非数値を含むベクトルを指定して関数を呼び出すと、検証関数 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)
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)
x1 =
0.1879
0.0326
0.6121
0.7674
y1 =
0.0326
0.6121
0.7674
0.1879
角度を 35 度に指定してこの関数を呼び出します。すると、左下の頂点が第 1 象限の外に出ます。x 座標が負になり、出力引数の検証を満たさないため、この関数はエラーを返します。
[x2,y2] = rotatePatch(35)
Invalid output 'xfinal'. Value must be positive. Error in rotatePatch (line 12) end
ベクトルのペアの繰り返しを受け入れて、各ペアの和を返す関数を作成します。入力および出力を行ベクトルに制限します。
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)
sum1 =
4 6
sum2 =
1 1入力は行ベクトルに制限されているため、ベクトルの各ペアの和は必ず行ベクトルになります。しかし、出力検証により、この関数が後で修正された場合でも確実に行ベクトルを生成するようにできます。たとえば、入力検証が関数 mustBeVector に変更された場合、ペアは変換されていない 1 つの行ベクトルと 1 つの列ベクトルで構成されることがあります。その場合、x1 と y2 の和は行列です。
x1 + y2
ans =
1 2
2 3
修正された repeatSum では、この行列が出力検証に合格しないため、出力はエラーとなります。
制限
引数ブロックは入れ子関数、抽象メソッド、またはハンドル クラスのデストラクター メソッドではサポートされません。
詳細
ヒント
データ型制限を使用すると、入力引数の暗黙の変換が行われます。以下に例を示します。
この関数では、stringfunction y = myFunction(inputArg1) arguments inputArg1 (1,1) double end ..."123"を入力引数として渡すと、MATLAB で string がdouble型の数値123に変換されます。検証関数では入力値は変更されないため、データ型の変換を回避するには、入力を制限するデータ型ではなく、1 つ以上の検証関数を使用します。以下に例を示します。
string から数値への変換を回避するには、
mustBeA、mustBeFloat、またはmustBeNumericを使用します。数値から string への変換を回避するには、
mustBeText、mustBeTextScalar、またはmustBeNonZeroLengthTextを使用します。サイズ変換を回避するには、
mustBeVectorまたはmustBeScalarOrEmptyを使用します。
MATLAB では、
argumentsブロックを含む関数のコードの補完と候補を、arguments ブロックに含まれている情報に基づいて提供できます。この情報は、functionSignatures.jsonファイルがなくても使用できます。コードの候補と補完のカスタマイズの詳細については、コードの候補と補完のカスタマイズを参照してください。
