プロパティの検証関数

MATLAB 検証関数

MATLAB^® はプロパティ検証で使用する関数を定義します。これらの関数は、検証のための一般的な使用パターンをサポートし、説明的なエラーメッセージを提供します。以下の表で、MATLAB 検証関数を分類し、その使用方法を説明しています。

数値属性

名前	意味	入力で呼び出される関数
`mustBePositive(value)`	`value > 0`	`gt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonpositive(value)`	`value <= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNonnegative(value)`	`value >= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNegative(value)`	`value < 0`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeFinite(value)`	`value` には、`NaN` 要素も `Inf` 要素もない。	`isfinite`
`mustBeNonNan(value)`	`value` には `NaN` 要素がない。	`isnan`
`mustBeNonzero(value)`	`value ~= 0`	`eq`, `isnumeric`, `islogical`
`mustBeNonsparse(value)`	`value` にはスパース要素がない。	`issparse`
`mustBeReal(value)`	`value` には虚数部がない。	`isreal`
`mustBeInteger(value)`	`value == floor(value)`	`isreal`, `isfinite`, `floor`, `isnumeric`, `islogical`
`mustBeNonmissing(value)`	`value` は欠損値を含むことができない。	`ismissing`

他の値との比較

名前	意味	入力で呼び出される関数
`mustBeGreaterThan(value,c)`	`value > c`	`gt`, `isreal`, `isnumeric`, `islogical`
`mustBeLessThan(value,c)`	`value < c`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeGreaterThanOrEqual(value,c)`	`value >= c`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeLessThanOrEqual(value,c)`	`value <= c`	`le`, `isreal`, `isnumeric`, `islogical`

データ型

名前	意味	入力で呼び出される関数
`mustBeA(value,classnames)`	`value` は特定のクラスでなければならない。	クラス定義の関係を使用
`mustBeNumeric(value)`	`value` は数値でなければならない。	`isnumeric`
`mustBeNumericOrLogical(value)`	`value` は数値または logical でなければならない。	`isnumeric`, `islogical`
`mustBeFloat(value)`	`value` は浮動小数点配列でなければならない。	`isfloat`
`mustBeUnderlyingType(value,typename)`	`value` には、基となる型が指定されていなければならない。	`isUnderlyingType`

サイズ

名前	意味	入力で呼び出される関数
`mustBeNonempty(value)`	`value` は空ではない。	`isempty`
`mustBeScalarOrEmpty(value)`	`value` はスカラーまたは空でなければならない。	`isscalar`, `isempty`
`mustBeVector(value)`	`value` はベクトルでなければならない。	`isvector`

メンバーシップおよび範囲

名前	意味	入力で呼び出される関数
`mustBeMember(value,S)`	`value` は `S` のメンバーの完全一致である。	`ismember`
`mustBeInRange(value,lower,upper,boundflags)`	`value` は範囲内になければならない。	`gt`, `ge`, `lt`, `le`

テキスト

名前	意味	入力で呼び出される関数
`mustBeFile(path)`	`path` はファイルを参照しなければならない。	`isfile`
`mustBeFolder(folder)`	`path` はフォルダーを参照しなければならない。	`isfolder`
`mustBeNonzeroLengthText(value)`	`value` は非ゼロ長のひとまとまりのテキストでなければならない。	該当なし
`mustBeText(value)`	`value` は string 配列、文字ベクトル、または文字ベクトルの cell 配列でなければならない。	該当なし
`mustBeTextScalar(value)`	`value` はひとまとまりのテキストでなければならない。	該当なし
`mustBeValidVariableName(varname)`	`varname` は有効な変数名でなければならない。	`isvarname`

関数を使用したプロパティの検証

クラス定義でプロパティの検証関数を使用して、プロパティ値に特定の制限を課します。関数によって課される特定の要件をプロパティ値が満たさない場合、検証関数は潜在的なプロパティ値を引数として受け入れ、エラーを発行します。

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

MATLAB 検証関数の一覧については、MATLAB 検証関数を参照してください。

検証関数の構文

検証関数を、関数名または引数のある関数呼び出しのコンマ区切りリストとして、中かっこで囲んで指定します。

classdef MyClass
   properties
      Prop {fcn1,fcn2,...} = defaultValue
   end
end

MATLAB は潜在的なプロパティ値を暗黙的に検証関数に渡します。ただし、検証関数が潜在的なプロパティ値に加えて入力引数も必要とする場合、プロパティと追加引数の両方を含めなければなりません。追加引数はリテラル値でなければならず、変数を参照できません。リテラル値は数字やテキストなどの非シンボリック表現です。

たとえば、関数 mustBeGreaterThan について考えます。入力パラメーターとして下限値が必要です。この検証関数では、プロパティ値がこの下限値より大きくなければなりません。

プロパティを最初の引数として渡します。プロパティ名を使用しますが、引用符で囲まないでください。このプロパティ定義は、Prop を 10 より大きい値に制限します。

properties
   Prop {mustBeGreaterThan(Prop,10)}
end

検証関数の使用

以下のクラスで各プロパティの検証関数を指定します。

Data は数値で有限でなければならない。
Interp はリストされている 3 つのオプションのいずれかでなければならない。このプロパティの既定値を指定してこの要件を満たします。

classdef ValidatorFunction
   properties
      Data {mustBeNumeric, mustBeFinite}
      Interp {mustBeMember(Interp,{'linear','cubic','spline'})} = 'linear'
   end
end

クラスの既定オブジェクトを作成すると初期値が表示されます。

a = ValidatorFunction

a = 

  ValidatorFunction with properties:

      Data: []
    Interp: 'linear'

プロパティに値を代入すると検証関数が呼び出されます。

a.Data = 'cubic'

Error setting property 'Data' of class 'ValidatorFunction':
Value must be numeric.

Data プロパティ検証には数値クラスが含まれないため、char ベクトルの数値への変換はありません。Data プロパティの検証を変更してクラスを double として指定する場合、MATLAB は char ベクトルを double 配列に変換します。

properties
   Data double {mustBeNumeric, mustBeFinite}
end

MATLAB が char ベクトルをクラス double に変換するため、char ベクトルへの代入を行ってもエラーは生成されません。

a.Data = 'cubic'

a = 

  ValidatorFunction with properties:

      Data: [99 117 98 105 99]
    Interp: 'linear'

Interp プロパティへの代入では完全一致が必要です。

a = ValidatorFunction;
a.Interp = 'cu'

Error setting property 'Interp' of class 'ValidatorFunction':
Value must be a member of this set
    linear
    cubic
    spline

列挙クラスを使用すると、大文字小文字を区別しないあいまい一致を利用できます。

あいまい一致のための列挙クラス

列挙クラスを使用するプロパティ検証には、次の利点があります。

明確な char ベクトルまたは string スカラーに対する、大文字小文字を区別しないあいまい一致
あいまい一致から正確な値への変換

たとえば、Interp プロパティの検証用に InterpMethod 列挙クラスを定義するとします。

classdef InterpMethod
   enumeration
      linear
      cubic
      spline
   end
end

InterpMethod クラスを使用するために Interp プロパティの検証を変更します。

classdef ValidatorFunction
   properties
      Data {mustBeNumeric, mustBeFinite}
      Interp InterpMethod
   end
end

'cubic' の最初の数文字に一致する値を代入します。

a = ValidatorFunction;
a.Interp = 'cu'

a = 

  ValidatorFunction with properties:

      Data: []
    Interp: cubic

検証関数の定義

検証関数は、プロパティ値と関数の引数値を検証するという特定の目的のために設計された通常の MATLAB 関数です。プロパティの検証に使用される関数は、次を行います。

潜在的なプロパティ値を入力引数として受け入れる
値を返さない
検証に失敗した場合はエラーをスローする

MATLAB 検証関数を使用して実行できない特定の検証を行う場合、独自の検証関数を作成すると便利です。ローカル関数をクラスファイル内に作成したり、任意のクラスで使用できるように関数を MATLAB パス上に配置することができます。

たとえば、ImgData クラスはローカル関数を使用して、サブクラスを除く Data プロパティを uint8 または uint16 の値のみに制限し、他の数値クラスからの変換を許可しない検証関数を定義します。事前定義された検証関数 mustBeInRange は、使用可能な値の範囲を制限します。

classdef ImgData
    properties
        Data {mustBeImData(Data), mustBeInRange(Data,0,255)} = uint8(0)
    end
end
function mustBeImData(a)
    % Check for specific class     
    if ~(isa(a,'uint8') || isa(a,'uint16'))
        eidType = 'ImData:notUint8OrUint16';
        msgType = 'Values assigned to Data property must be uint8 or uint16 data.';
        throwAsCaller(MException(eidType,msgType))
    end
end

ImgData クラスのインスタンスを作成するときに、MATLAB は既定値が 0...255 の範囲にあり、空でない uint8 または uint16 の値であることを検証します。この既定値は、プロパティに代入する他の値と同様に、検証の要件を満たさなければならない点に注意してください。

a = ImgData

a = 

  ImgData with properties:

    Data: 0

プロパティへの代入を行うと、検証関数が左から右の順序で呼び出されます。char ベクトルを Data プロパティに代入すると、mustBeImData によってエラーがスローされます。

a.Data = 'red';

Error setting property 'Data' of class 'ImgData'. Value assigned to
Data property is not uint8 or uint16 data.

範囲外の数値を代入すると、mustBeInRange によってエラーがスローされます。

a.Data = uint16(312);

Error setting property 'Data' of class 'ImgData'. Value must be greater
than or equal to 0, and less than or equal to 255.

関連する関数については、mustBeInteger、mustBeNumeric および mustBePositive を参照してください。