Main Content

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

関数の引数の検証

引数の検証の紹介

関数の引数の検証は、関数の入力引数に特定の制限を宣言するための 1 つの方法です。引数の検証を使用すると、関数の入力値のクラス、サイズ、および他の特性を制約することができ、これらのテストを実行するコードを関数本体に記述する必要はありません。

関数の引数の検証は宣言型であるため、MATLAB® デスクトップ ツールで特定のコード ブロックを調べて関数に関する情報を抽出できます。入力引数の要件を宣言することにより、煩雑な引数チェックのコードをなくし、コードの可読性、ロバスト性、および保守性を向上させることができます。

関数の引数の検証構文により、オプション引数、繰り返し引数、および名前と値の引数を定義するプロセスが簡略化されます。また、この構文を使用すると、一貫した方法で既定値を定義できるようになります。

引数の検証を使用する場所

関数の引数の検証は、関数定義でオプションとして使用します。引数の検証が最も役に立つのは、任意のコードで呼び出され、関数コードを実行する前に入力の有効性を判定しなければならない関数内です。作成者以外が使用するために設計されている関数では、引数入力に対する適切なレベルの制限と、その関数への入力に基づいて特定のエラー メッセージを返す機会があると、役立つ場合があります。

検証が必要でない場所

ローカル関数とプライベート関数、およびプライベート メソッドや保護されたメソッドでは、呼び出し元で入力の要件が認識されるため、これらのタイプの関数は有効な引数を指定して呼び出すことができます。

検証が許可されていない場所

引数の検証構文は、入れ子関数、抽象メソッド、またはハンドル クラスのデストラクター メソッドでは使用できません。メソッド内での引数の検証の詳細については、クラス メソッド内での引数の検証を参照してください。

arguments ブロック構文

関数は、キーワード arguments および end で区切られたコード ブロック内で引数の検証を定義します。使用した場合、arguments ブロックは関数の最初の実行可能行より前に開始されなければなりません。

関数内で複数の arguments ブロックを使用できますが、すべてのブロックは、arguments ブロックの一部ではないコードより前になければなりません。

以下のコードの強調表示されている部分は、引数検証の構文を示しています。

関数の引数の宣言には、以下の種類の制限をどれでも含めることができます。

  • サイズ — 各次元の長さ。小かっこで囲みます。

  • クラス — 単一の MATLAB クラスの名前。

  • 関数 — 検証関数のコンマ区切りリスト。中かっこで囲みます。

入力引数の既定値を、その引数についての関数の検証宣言内で定義することもできます。既定値は、その引数に対して宣言された制限を満たさなければなりません。

サイズ

検証サイズは入力引数の次元であり、非負の整数値またはコロン (:) で指定します。コロンは、その次元で任意の長さが許可されることを示します。次元には式を使用できません。関数呼び出しで引数に代入される値は、指定されたサイズと適合していなければならず、そうでない場合、MATLAB はエラーをスローします。

サイズの指定には、MATLAB のインデックス付き代入の規則が適用されます。たとえば、1 行 1 列の値は (5,3) として指定されたサイズと適合しますが、これは、MATLAB でスカラー拡張が適用されるためです。また、MATLAB の行と列の変換が適用され、(1,:) と指定されたサイズは 1 行 n 列および n 行 1 列のサイズを受け入れることができます。

以下にいくつかの例を示します。

  • (1,1) — 入力は厳密に 1 行 1 列でなければならない。

  • (3,:) — 最初の次元は 3 でなければならず、2 番目の次元は任意の値にできる。

サイズを指定しない場合、検証関数で制限されていない限り、任意のサイズが許可される。

クラス

検証クラスは単一のクラスの名前です。関数の入力に代入される値は、指定されたクラスであるか、指定されたクラスに変換可能でなければなりません。Java クラスと COM クラス、および classdef キーワードを使用しない MATLAB クラス定義 (MATLAB ソフトウェア Version 7.6 より前に定義されたクラス) を除く、任意の MATLAB クラス、または MATLAB でサポートされている外部定義クラスを使用してください。

以下にいくつかの例を示します。

  • char — 入力は char クラスか、または string のように MATLAB で char に変換可能な値でなければならない。

  • double — 任意の精度の数値が入力可能。

  • cell — 入力は cell 配列でなければならない。

  • 列挙型クラスなど、ユーザー定義のクラスでは入力をより具体的な値に制限でき、サポートされる変換を制御できる。

クラスを指定しない場合、検証関数で制限されていない限り、任意のクラスが許可される。

検証関数

検証関数は、引数値が特定の要件を満たさない場合にエラーをスローする MATLAB 関数です。検証関数は値を返さず、クラスやサイズとは異なり、検証対象の引数の値を変更できません。

検証プロセス中、MATLAB は引数用にリストされている各検証関数にその引数の値を渡します。検証関数に渡される値は、クラスとサイズの指定によって行われた変換の結果です。MATLAB は各関数を左から右の順序で呼び出し、最初に見つかったエラーをスローします。

事前定義された検証関数の表は、引数の検証関数を参照してください。

既定値

引数の既定値には、サイズ、クラス、および検証関数の各要件を満たす任意の定数または式を使用できます。引数の宣言で既定値を指定すると、その引数は任意になります。MATLAB は、関数呼び出しに引数が含まれていない場合、その既定値を使用します。既定値の式は、既定値が使用されるたびに評価されます。

メモ

MATLAB は、引数の値を指定せずに関数が呼び出された場合にのみ既定値を検証するため、無効な既定値は、その引数を指定せずに関数が呼び出された場合にのみエラーになります。

オプションの引数は、関数シグネチャと arguments ブロック内で必須の引数の後に配置しなければなりません。オプションの引数の詳細については、必須の位置引数とオプションの位置引数を参照してください。

検証シーケンス

引数は、arguments ブロックで上から下へと検証されます。MATLAB は引数宣言の各部分を特定の順序で検証します。最初にクラスが、次にサイズが検証されます。クラスとサイズの検証結果が検証関数に渡されます。クラス、サイズ、検証関数が引数宣言にあるかどうかによって、各ステップは任意になります。

詳細については、引数の検証の順序を参照してください。

宣言されたクラスおよびサイズへの変換

MATLAB の標準的な変換規則により、クラス検証とサイズ検証はどちらも入力引数の値を変更できます。そのため、関数本体で検証された値が、関数の呼び出し時に渡された値と異なる場合があります。変換規則は、MATLAB が次の形式のインデックス付き代入に適用する規則から派生しています。

A(indices) = value

MATLAB は、左辺の値にクラスやサイズに関する要件があるかどうかを判定でき、場合によっては、右辺の値を必要なクラスやサイズに変換できます。

関連情報については、クラスとサイズの変換の回避を参照してください。

引数の検証の例

次の arguments ブロックは、3 つの入力のサイズとクラスを指定します。

function out = myFunction(A, B, C)   
    arguments
        A (1,1) string 
        B (1,:) double
        C (2,2) cell
    end

    % Function code
    ...
end

この関数では、変数は以下の検証要件を満たさなければなりません。

  • A は string スカラー。

  • B は 1 行で任意の長さ列の double のベクトル。

  • C は 2 行 2 列の cell 配列。

値の変換

以下の関数は、arguments ブロックで指定されたクラスと一致させるために、入力を変換する方法を示しています。SpeedEnum クラスは、3 番目の入力引数が取り得る値を定義するために作成された列挙型クラスです。

function forwardSpeed(a,b,c)
    arguments
        a double
        b char
        c SpeedEnum
    end

    % Function code
    disp(class(a))
    disp(class(b))
    disp(class(c))
end

列挙型クラスは次のようになります。

classdef SpeedEnum < int32
    enumeration
        Full   (100)
        Half   (50)
        Stop   (0)
    end
end

関数に対するこの呼び出しでは、宣言された型に MATLAB が変換できる入力値が使用されます。関数内の実際の引数の型が出力として表示されます。

forwardSpeed(int8(4),"A string",'full')
double
char
SpeedEnum

検証関数を使用した特定の制限

検証関数は、より具体的な方法で入力引数を制限できます。事前定義された検証関数を多くの一般的な種類の検証に使用したり、特定の要件を満たす独自の検証関数を定義することができます。

たとえば、以下の関数は mustBeNumericmustBeRealmustBeMember、およびローカル関数 mustBeEqualSize を使用して、次の検証を指定します。

  • 入力 x は任意の長さの実数値行ベクトルでなければならない。

  • 入力 vx と同じサイズの実数値行ベクトルでなければならない。

  • 入力 method は、許可された 3 つの選択肢のいずれかにあたる文字ベクトルでなければならない。method は既定値を指定しているため、この引数は任意です。

function myInterp(x,v,method)
    arguments
        x (1,:) {mustBeNumeric,mustBeReal}
        v (1,:) {mustBeNumeric,mustBeReal,mustBeEqualSize(v,x)}
        method (1,:) char {mustBeMember(method,{'linear','cubic','spline'})} = 'linear'
    end
    % Function code
    ....
end

% Custom validation function
function mustBeEqualSize(a,b)
    % Test if a and b have equal size 
    if ~isequal(size(a),size(b))
        error('Size of first input must equal size of second input')
    end
end

関数の引数の検証は、カスタムの検証関数内では使用しないでください。検証関数の定義の詳細、および事前定義された検証関数のリストについては、引数の検証関数を参照してください。

引数の種類

関数の引数の検証では、4 種類の引数を宣言できます。関数は、これらの種類の引数をどれでも定義できますが、引数は以下の順序で定義しなければなりません。

  1. 必須の位置引数

  2. オプションの位置引数

  3. 繰り返しの位置引数

  4. オプションの名前と値の引数

必須の位置引数とオプションの位置引数

位置引数は、特定の順序で関数に渡さなければなりません。引数リスト内で値が渡される位置は、arguments ブロックで引数が宣言される順序に対応していなければなりません。arguments ブロック内の引数名はすべて一意でなければなりません。

arguments ブロック内の位置引数は、引数で既定値が定義されていない限り、関数の呼び出しに際して必要です。引数の宣言で既定値を指定すると、位置関数は任意になります。これは、関数呼び出しで値が渡されない場合、MATLAB は既定値を使用できるためです。

既定値には、定数か、または引数宣言を満たす結果を生成する式を指定できます。式は、arguments ブロック内でそれより前に宣言されている引数を参照できますが、それより後に宣言される引数は参照できません。

MATLAB は、関数呼び出しに引数が含まれていない場合にのみ、既定値の式を評価します。

arguments ブロックでは、すべてのオプションの引数を、すべての必須の引数の後に配置しなければなりません。たとえば、次の引数ブロックでは、maxvalminval は既定値をもつためオプションとなります。

function myFunction(x,y,maxval,minval)
    arguments
        x (1,:) double
        y (1,:) double
        maxval (1,1) double = max(max(x),max(y))
        minval (1,1) double = min(min(x),min(y))
    end

    % Function code
    ....
end

この関数は、次のいずれかの構文を使用して呼び出すことができます。

myFunction(x,y,maxval,minval) 
myFunction(x,y,maxval) 
myFunction(x,y) 

オプションの位置引数は、後続の引数を識別するために関数呼び出し内でその位置を埋める必要がある場合には、必須になります。つまり、minval の値を指定する場合は、maxval の値を指定しなければなりません。

無視される位置引数

MATLAB では、チルダ文字 (~) を引数の代わりに渡すことにより、入力引数を無視できます。関数シグネチャの引数の位置に対応する arguments ブロック内で、チルダ文字 (~) を追加することで、未使用の位置引数を無視する関数を定義できます。関数シグネチャ内の無視される引数それぞれにチルダ文字 (~) を追加します。

無視される引数は既定値をもつことができず、また、クラス、サイズ、検証関数を指定できません。

チルダ文字 (~) は、その後に必須の位置関数が続いていない場合、オプションの入力引数として扱われます。たとえば、次の関数ではチルダ文字 (~) はオプションの引数を表します。

function c = f(~)
    arguments
        ~
    end

    % Function code
end

この関数は、引数を指定せずに呼び出すことができます。

c = f 

また、この関数は、1 つの引数を指定して呼び出すこともできます。

c = f(2)

次の関数では、チルダ文字 (~) は必須の引数を表します。

function c = f(~,x)
    arguments
        ~
        X
    end

    % Function code
    ...
end

この関数の呼び出しには、どちらの引数も含まれていなければなりません。

c = f(2,3)

無視される入力を指定した関数呼び出しの詳細については、関数入力の無視を参照してください。

繰り返し引数

繰り返し引数は、入力引数として繰り返し指定可能な位置引数です。Repeating 属性を含む arguments ブロック内で繰り返し引数を宣言します。

arguments (Repeating)
    arg1
    arg2
    ...
end

関数は Repeating arguments ブロックを 1 つのみもつことができ、これには 1 つ以上の繰り返し引数を含めることができます。

Repeating arguments ブロックを定義する関数は、ブロック内のすべての引数の 0 回以上の出現で呼び出すことができます。関数の呼び出しに繰り返し引数が含まれる場合、Repeating arguments ブロック内のすべての引数がそれぞれの繰り返しに含まれていなければなりません。

たとえば、Repeating arguments ブロックが引数 x および y を定義する場合は、それぞれの繰り返しに xy の両方が含まれていなければなりません。

繰り返し引数は既定値を指定できないため、オプションにはできません。ただし、繰り返し引数を含めずに関数を呼び出すことはできます。

関数では、繰り返し引数を位置引数の後に、かつ名前と値の引数の前に宣言しなければなりません。名前と値の引数は Repeating ブロック内で指定できません。名前と値の引数の詳細については、名前と値の引数を参照してください。

関数内で、各繰り返し引数は、関数呼び出しで渡される繰り返しの数と等しい数の要素をもつ cell 配列になります。cell 配列の各要素に検証が適用されます。この引数の使用を 0 に指定して関数を呼び出すと、cell 配列のサイズは 1 行 0 列になります。つまり、これは空になります。

たとえば、次の関数では 3 つの繰り返し引数 xy、および option のブロックが宣言されます。

function [xCell,yCell,optionCell] = fRepeat(x,y,option)
    arguments (Repeating)
        x double
        y double
        option {mustBeMember(option,["linear","cubic"])}
    end
    
    % Function code
    % Return cell arrays
    xCell = x;
    yCell = y;
    optionCell = option;
end

入力なし、または 3 の倍数回入力を指定してこの関数を呼び出すことができます。MATLAB は、各引数に対して、その引数に渡されるすべての値を含む cell 配列を作成します。次の fRepeat の呼び出しでは、3 つの繰り返し引数が 2 セット渡されます。

[xCell,yCell,optionCell] = fRepeat(1,2,"linear",3,4,"cubic")
xCell =

  1×2 cell array

    {[1]}    {[3]}


yCell =

  1×2 cell array

    {[2]}    {[4]}


optionCell =

  1×2 cell array

    {["linear"]}    {["cubic"]}

次の関数は、Repeating arguments ブロック内で xy の入力に繰り返し引数を受け入れます。この関数の本体において、繰り返し引数として指定された値は cell 配列 x および y で使用できます。この例では、plot(x1,y1,…) のように x および y の値を交互に配置して、関数 plot に必要な入力に一致させています。

function myPlotRepeating(x,y)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
    end

    % Function code
    % Interleave x and y
    z = reshape([x;y],1,[]);

    % Call plot function
    if ~isempty(z)
        plot(z{:});
    end
end

入力引数の繰り返しのペアを指定して、この関数を呼び出します。

x1 = 1:10;
y1 = sin(x1);
x2 = 0:5;
y2 = sin(x2);
myPlotRepeating(x1,y1,x2,y2)

繰り返し引数に varargin を使用しない

引数検証を使用する関数で varargin を使用することは推奨されません。varargin のサイズとクラスが繰り返し引数ブロック内で制限されている場合、この制限は varargin のすべての値に適用されます。

レガシ コードをサポートするために varargin を使用する場合、これは Repeating arguments ブロック内の唯一の引数でなければなりません。

たとえば、次の関数は 2 つの必須の位置引数に加えて、varargin を繰り返し引数として定義します。

function f(a, b, varargin)
    arguments
        a uint32
        b uint32
    end
    arguments (Repeating)
        varargin
    end
    
    % Function code
    ...
end

名前と値の引数

名前と値の引数は、関数に渡される値に名前を関連付けます。名前と値の引数には、次の特徴があります。

  • 任意の順序で関数に渡すことができる

  • 常にオプションである

  • すべての位置引数と繰り返し引数の後に宣言しなければならない

  • Repeating 属性を使用する arguments ブロック内では使用できない

  • 名前と値の構造体を複数使用する場合でも、一意の名前を使用しなければならない

  • 位置引数にも使用されている名前は使用できない

ドット表記を使用して arguments ブロック内で名前と値の引数を宣言し、構造体のフィールドを定義します。たとえば、NameValueArgs という名前の構造体は、2 つの名前と値の引数 Name1 および Name2 を定義します。任意の有効な MATLAB 識別子を構造体名として使用できます。

arguments
    NameValueArgs.Name1
    NameValueArgs.Name2
end

構造体名は関数シグネチャ内になければなりません。

function myFunction(NameValueArgs)

string または文字ベクトルとして渡された、名前と値の構造体のフィールド名を使用して、関数を呼び出します。

myFunction('Name1',value1,'Name2',value2)

関数シグネチャ内で使用される構造体の名前は、関数に渡される名前と値を含む関数ワークスペース内の構造体の名前です。

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

    % Function code
    result = NameValueArgs.Name1 * NameValueArgs.Name2;
end
r = myFunction('Name1',3,'Name2',7)
r =

    21

名前と値の引数の既定値

それぞれの名前に既定値を指定できます。既定値を指定せずに、その名前と値の引数なしで関数が呼び出される場合、そのフィールドは名前と値の構造体に存在しません。名前と値の引数が関数に渡されない場合、MATLAB は構造体を作成しますが、そこにフィールドはありません。

関数呼び出しで渡された名前と値の引数を特定するには、関数 isfield を使用します。

たとえば、次の関数は 2 つの必須の位置引数 (widthheight) および 2 つの名前と値の引数 (LineStyleLineWidth) を定義します。この例では、options 構造体には 2 つのフィールド (LineStyleLineWidth) があり、既定値か、または関数の呼び出し時に名前と値の引数として指定された値が含まれています。

function myRectangle(width,height,options)
    arguments
        width double
        height 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)

繰り返し引数および名前と値の引数の使用

関数で繰り返し引数が定義されている場合、繰り返し引数ブロックに続く別の arguments ブロック内で名前と値の引数を宣言しなければなりません。たとえば、次の関数は 2 つの繰り返し引数 xy を受け入れます。xy の繰り返しをすべて指定した後に、値 lin または log を名前 PlotType に代入する名前と値のペアを指定できます。

関数呼び出しに PlotType 引数が含まれるかどうかを判定するには、関数 isfield を使用して scale 構造体の PlotType フィールドをチェックします。

function linLog(x,y,scale)
    arguments(Repeating)
        x (1,:) double
        y (1,:) double
    end
    arguments
        scale.PlotType (1,1) string
    end
    z = reshape([x;y],1,[]);
    if isfield(scale,"PlotType")
        if scale.PlotType == "lin"
            plot(z{:})
        elseif scale.PlotType =="log"
            loglog(z{:})
        end
    end
end

名前と値の引数を指定して、または指定せずに、この関数を呼び出します。

myLinLog(1:5,1:5)
myLinLog(1:5,1:5,1:10,1:100:1000)
myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")

複数の名前と値の構造体

関数の引数ブロックには、複数の名前と値の構造体を含めることができます。ただし、フィールド名は構造体全体で一意でなければなりません。以下の関数には、lineOptionsfillOptions という 2 つの名前と値の構造体があります。これらの構造体は同じフィールド名をもつことができません。

関数 myRectangle の引数は次のとおりです。

  • widthheightdouble 型の必須の位置引数である。

  • lineOptions.LineStyle は既定値 "-" をもつスカラー string である。

  • lineOptions.LineWidth は既定値 1 をもつスカラー数値である。

  • fillOptions.Color は string である。

  • fillOptions.Pattern には値の制限がない。

function myRectangle(width,height,lineOptions,fillOptions)
    arguments
        width double
        height double
        lineOptions.LineStyle (1,1) string = "-"
        lineOptions.LineWidth (1,1) {mustBeNumeric} = 1
        fillOptions.Color string
        fillOptions.Pattern
    end

    % Function Code
    ...
end

クラス プロパティからの名前と値の引数

MATLAB には、クラスのパブリック プロパティを名前と値の引数の名前に使用する便利な関数構文があります。クラスで定義されたすべての設定可能なプロパティ (つまり、パブリックの SetAccess をもつすべてのプロパティ) に名前と値の引数を指定するには、arguments ブロックで次の構文を使用します。

structName.?ClassName

関数は、"structName.? ClassName" 構文を 1 回だけ使用できます。したがって、関数は、異なるクラスと構造体名を使用する場合でも、クラスからフィールド名を取得する名前と値の構造体は 1 つしか定義できません。

クラスでプロパティ検証を使用して、プロパティに代入できる値を制限している場合、関数はその検証を個々の名前と値の引数に適用します。プロパティ検証の詳細については、プロパティ値の検証を参照してください。

たとえば、次の関数は 2 つの必須の引数 xy をもち、matlab.graphics.chart.primitive.Bar クラスの任意のパブリック プロパティ名と値を受け入れます。

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

必須の入力と、任意の設定可能なプロパティの名前と値のペアを指定して、関数を呼び出します。

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,'FaceColor','magenta','BarLayout','grouped')

特定のプロパティのオーバーライド

arguments ブロック内で、プロパティ名を特定の名前と値の引数で再定義することにより、クラスのプロパティ検証をオーバーライドできます。

structName.?ClassName
structName.PropertyName (dim1,dim2,...) ClassName {fcn1,fcn2,...}

特定の名前と値の引数の検証は、個別に指定されたプロパティ名に対しクラスで定義された検証をオーバーライドします。

たとえば、以下の関数は名前と値の引数を matlab.graphics.chart.primitive.Bar クラスのプロパティとして定義します。また、この関数は、特定の値 red または blue のみが許可されるように、プロパティ名 FaceColor をオーバーライドします。

matlab.graphics.chart.primitive.Bar クラスでの FaceColor の既定値は、制限された値 (red または blue) のいずれでもありません。したがって、オーバーライドする宣言では、検証関数 mustBeMember によって課された制限を満たす既定値を代入しなければなりません。つまり、既定値は red または blue でなければなりません。

この関数は関数 namedargs2cell を使用して、名前と値の構造体を、交互に配置された名前と値を含む cell 配列に変換します。

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
        propArgs.FaceColor {mustBeMember(propArgs.FaceColor,{'red','blue'})} = "blue"
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

2 つの必須の引数 xy を使用して関数を呼び出します。オプションで、関数 bar でサポートされる任意の名前と値のペアと、FaceColor の値 (red または blue のいずれか) を渡します。FaceColor の他の値は許可されません。

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,'FaceColor','red','BarLayout','grouped')

クラス メソッド内での引数の検証

メソッド入力引数の検証はパブリック メソッド内で有用です。これは、メソッドの呼び出しがクラス コードから発生していない可能性があるためです。関数の引数の検証は、抽象クラスで定義された具象メソッドを含む具象クラス メソッドで使用できます。ただし、具象メソッド (クラスによって実装されていないメソッド) は、arguments ブロックを定義できません。クラス メソッドの詳細については、メソッドおよび抽象クラスとクラス メンバーを参照してください。

classdef ファイルに、別々のファイルで定義されたメソッドのメソッド プロトタイプが含まれる場合、メソッドを定義しているその別々のファイルに arguments ブロックを含めます。別のファイルでメソッドを定義する方法の詳細については、別ファイルのメソッドを参照してください。

サブクラス メソッドは、関数の引数の検証を継承しません。スーパークラス メソッドをオーバーライドするサブクラス メソッドでは、スーパークラス メソッドで使用されているものと同じ引数の検証をサブクラス メソッドに追加できます。

ハンドル クラスのデストラクター メソッドは、引数の検証を使用できません。arguments ブロックを含むハンドル サブクラス内の delete という名前のメソッドは、デストラクターとして扱われません (つまり、オブジェクトが破棄されるときに MATLAB で呼び出されない)。クラス デストラクター メソッドの詳細については、ハンドル クラスのデストラクターを参照してください。

引数の検証の順序

関数が呼び出されると、MATLAB は入力引数をそれらが arguments ブロックで宣言されている順序、つまり上から下への順序で検証します。各引数は、次の引数が検証される前に完全に検証されます。したがって、前に宣言された引数へのすべての参照では、検証済みの値が使用されます。最初の検証が失敗すると、関数はエラーをスローします。

検証された値は、関数の呼び出しに際して入力として渡された元の値と異なる場合があります。たとえば、次の関数はクラス uint32 の値として入力を宣言します。3 番目の入力の宣言は、最初の 2 つの入力の積に等しい既定値を代入します。

function c = f(a, b,c)
    arguments
        a uint32
        b uint32
        c uint32 = a .* b
    end

    % Function code
    ...
end

異なる数値クラス (double など) の入力を指定して関数を呼び出すと、uint32 に変換される結果となります。

c = f(1.8,1.5)

関数呼び出しでオプションの入力引数 c が指定されていないため、MATLAB は、a および buint32 値に変換した後、既定値を評価して c に代入します。この場合、変換の結果、どちらの入力の値も 2 になります。したがって、ab の積は 4 になります。

c =

  uint32

   4

3 番目の入力に値を指定する場合、関数は値を c に代入し、既定値の式は評価しません。

c = f(1.8,1.5,25)
c =

  uint32

   25

クラスとサイズの変換の回避

検証プロセス中、MATLAB は検証関数を呼び出す前に、クラスの検証を適用してから、サイズの検証を適用します。関数呼び出しで省略されているオプションの入力に既定値が使用されている場合、検証プロセスを適用する前に、この値が引数に代入されます。

関数に渡される引数の値が検証に必要なクラスとサイズに一致しない場合、MATLAB は、変換が可能であれば、その値を宣言されたクラスとサイズに変換します。ただし、変換が望ましい動作ではない場合があります。

MATLAB で実行可能な変換の例をここにいくつか挙げます。

数値クラスの制限を満たす場合は次のとおりです。

  • char 値をその Unicode® 数値に変換可能。

  • string が単一の数値を表していない場合、string を数値または NaN に変換可能。

サイズの制限を満たす場合は次のとおりです。

  • スカラー拡張はサイズをスカラーから非スカラーに変更可能。

  • 列ベクトルを行ベクトルに変換可能。

MATLAB によって実行される標準の変換を入力引数の検証から排除するには、クラスおよびサイズの制限の代わりに検証関数を使用します。検証関数の呼び出しは値を返さず、入力引数の値を変更することはできません。

たとえば、次の関数は最初の入力を、double クラスである任意サイズの 2 次元配列に制限します。2 番目の入力は、任意のクラスの 5 行 3 列の配列でなければなりません。

function f(a, b)
    arguments
        a (:,:) double
        b (5,3)
    end

    % Function code
    ...
end

MATLAB の標準の型変換とスカラー拡張のため、次の入力を指定してこの関数を呼び出しても検証エラーを受け取ることはありません。

f('character vector',144)

既定で、MATLAB は文字ベクトルの要素を等価な数値に変換し、スカラー拡張を適用してスカラー値 144 から 5 行 3 列の配列を作成します。

特殊な検証関数を使用して、より具体的な入力引数の検証を行うことができます。たとえば、次の関数は、最初と 2 番目の引数に対するクラスとサイズの指定の代わりに使用する、2 つの特殊な検証関数を定義します。これらのローカル関数によって、入力値の変換を回避できるようになります。

function fCustomValidators(a, b)
    arguments
        a {mustBeA(a,'double'), mustBeDims(a,2)}
        b {mustBeSize(b,[5,3])}
    end

    % Function code
    ...
end

% Custom validator functions
function mustBeA(input,className)
    % Test for specific class
    if ~isa(input,className)
        error('Input must be of class double.')
    end
end

function mustBeSize(input,sizeDims)
    % Test for specific size
    if ~isequal(size(input),sizeDims)
        error(['Input must be of size ',num2str(sizeDims)])
    end
end

function mustBeDims(input,numDims)
    % Test for number of dimensions
    if ~isequal(length(size(input)),numDims)
        error(['Input must have ',num2str(numDims),' dimensions.'])
    end
end

検証関数 mustBeSize および mustBeDims は、入力引数の厳密な宣言を強制します。

fCustomValidators('character vector',144)
Invalid input argument at position 1. Input must be of class double

この呼び出しでは、最初の引数の次元数が正しくないため、検証関数はカスタム エラー メッセージを返します。

fCustomValidators(ones(2,2,4),144)
Invalid input argument at position 1. Input must have 2 dimensions

検証関数 mustBeSize は 2 番目の入力を特定の次元に制限します。この次元はエラー メッセージに提示されます。

fCustomValidators(ones(2,2),144)
Invalid input argument at position 2. Input must be of size [5  3]

引数の検証での nargin

関数 nargin は、現在実行中の関数の呼び出し時に渡された関数入力引数の数を返します。関数の引数の検証を使用する場合、関数内で nargin から返される値は、関数の呼び出し時に指定された位置引数の数です。

繰り返し引数は位置引数であるため、関数の呼び出し時に渡された繰り返し引数の数は nargin で返される値に含まれます。

nargin が返す値には、関数呼び出しに含まれていないオプションの引数は含まれません。また、nargin は名前と値の引数をカウントしません。

関数の呼び出し時にオプションの位置引数が渡されるかどうかを判定するには、nargin を使用します。たとえば、次の関数は 3 つの位置引数と 1 つの名前と値の引数を宣言します。呼び出しに際して渡される引数を関数がどのように判定するかを以下に示します。

  • nargin は、オプションの位置引数 c が関数に渡されるかどうかを switch ブロックで判定。

  • isfield は、Format の名前と値の引数が関数に渡されるかどうかを判定。

function result = fNargin(a, b, c, namedargs)
    arguments
        a (1,1) double
        b (1,1) double
        c (1,1) double = 1
        namedargs.Format (1,:) char
    end

    % Function code
    switch nargin
        case  2
            result = a + b;
        case 3
            result = a^c + b^c;
    end
    if isfield(namedargs,'Format')
        format(namedargs.Format);
    end
end

この関数呼び出しでは、nargin の値は 2 です。

result = fNargin(3,4)
result =

     7

この関数呼び出しでは、nargin の値は 3 です。

result = fNargin(3,4,7.62)
result =

   4.3021e+04

この関数呼び出しでは、nargin の値は 3 です。

result = fNargin(3,4,7.62,'Format','bank')
result =

      43020.56

変数および関数へのアクセスの制限

arguments ブロックは関数のワークスペース内にあります。import コマンドを使用して関数のスコープに追加されたパッケージ、クラスまたは関数はすべて、arguments ブロックのスコープに追加されます。

検証関数と既定値の式から参照できる変数は、既に宣言されている入力変数のみです。次の関数では、c の既定値は ab から派生します。

function c = f(a,b,c)
    arguments
        a uint32
        b uint32
        c uint32 = a * b
    end
 
    % Function code
    ...
end

しかし、arguments ブロックでまだ宣言されていない入力変数は、参照できません。たとえば、前の関数で次の宣言を引数 a に使用することは有効ではありません。これは、bc がまだ宣言されていないためです。

arguments
    a uint32 = b * c
    b uint32
    c uint32
end

引数の検証の式は、先に宣言された引数、つまり検証済みの引数のみを参照できます。検証関数と、名前と値の引数の既定値は、他の名前と値の引数にアクセスできません。

arguments ブロック内の関数の制限

先に宣言された変数への参照はすべて、検証関数と既定値のテキスト内で可視でなければなりません。コードの透明性を確保するため、関数ワークスペースとやり取りする関数は使用しないでください。具体的には、入れ子関数や次の表にリストされている関数を arguments ブロックで使用しないでください。

assigninbuiltinclear
dbstackevalevalc
evalinexistfeval
inputinputnameload
narginnarginchknargoutchk
savewhoswho

これらの制限は、arguments ブロック内でのみ適用され、関数本体の変数や関数には適用されません。

参考

|

関連するトピック