ドキュメンテーション

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

プロパティの検証関数

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

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

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

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

検証関数の構文

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

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

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

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

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

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 検証関数、その意味、および検証関数で使用される MATLAB 関数の一覧です。

名前

意味

依存関係

mustBePositive(A)

A > 0

gtisrealisnumericislogical

mustBeNonpositive(A)

A <= 0

geisrealisnumericislogical

mustBeFinite(A)

A には、NaN 要素も Inf 要素もない。

isfinite

mustBeNonNan(A)

A には NaN 要素がない。

isnan

mustBeNonnegative(A)

A >= 0

geisrealisnumericislogical

mustBeNegative(A)

A < 0

ltisrealisnumericislogical

mustBeNonzero(A)

A ~= 0

eqisnumericislogical

mustBeGreaterThan(A,B)

A > B

gtisscalarisrealisnumericislogical

mustBeLessThan(A,B)

A < B

ltisrealisnumericislogical

mustBeGreaterThanOrEqual(A,B)

A >= B

geisrealisnumericislogical

mustBeLessThanOrEqual(A,B)

A <= B

leisrealisnumericislogical

mustBeNonempty(A)

A は空ではない。

isempty

mustBeNonsparse(A)

A にはスパース要素がない。

issparse

mustBeNumeric(A)

A は数値である。

isnumeric

mustBeNumericOrLogical(A)

A は数値または論理値である。

isnumericislogical

mustBeReal(A)

A には虚数部がない。

isreal

mustBeInteger(A)

A==floor(A)

isrealisfinitefloorisnumericislogical

mustBeMember(A,B)

AB のメンバーの完全一致である。

ismember

検証関数の定義

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

  • 潜在的なプロパティ値を入力引数として受け入れる

  • 値を返さない

  • 検証に失敗した場合はエラーをスローする

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

たとえば、ImData クラスはローカル関数を使用して Data プロパティを特定の数値範囲に制限する検証関数を定義します。

classdef ImData
   properties
      Data {mustBeNumeric, mustBeInRange(Data,[0,255])} = 0
   end
end
function mustBeInRange(a,b)
   if any(a(:) < b(1)) || any(a(:) > b(2))
      error(['Value assigned to Data property is not in range ',...
         num2str(b(1)),'...',num2str(b(2))])
   end
end

ImData クラスのインスタンスを作成するとき、MATLAB は既定値が 0...255 の範囲にある空でない数値であることを検証します。

a = ImData
a = 

  ImData with properties:

    Data: 0

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

a.Data = 'red'
Error setting property 'Data' of class 'ImData':
Value must be numeric.

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

a.Data = -1
Error setting property 'Data' of class 'ImData':
Value assigned to Data property is not in range 0...255

検証関数のサポートの追加

依存関数をクラスのメソッドとして実装することにより、クラスのオブジェクトで MATLAB 検証関数がサポートされるようにします。各関数に実装するメソッドを特定するには、この表MATLAB 検証関数にリストされている検証関数のリファレンス ページを参照してください。

たとえば、クラスで mustBeGreaterThan 検証関数がサポートされるようにするとします。以下の MATLAB 関数をクラスでメソッドとしてオーバーロードします。

  • isrealmustBeGreaterThan は複素数をサポートしないため、常に論理値 true を返します。

  • gtmustBeGreaterThan の要件として、比較の 2 番目のオブジェクトはスカラーでなければなりません。

SupportmBGT クラスが mustBeGreaterThan のサポートを実装します。

classdef SupportmBGT
   properties
      Prop(1,1) double {mustBeReal}
   end
   methods
      function obj = SupportmBGT(data)
         if nargin > 0
            obj.Prop = data;
         end
      end
      function tf = isreal(obj)
         tf = true;
      end
      function tf = gt(obj1, obj2)
         tf = [obj1(:).Prop] > obj2.Prop;
      end
   end
end

このクラスのオブジェクトに対して mustBeGreaterThan を使用します。

a = SupportmBGT(10);
b = SupportmBGT(12);
mustBeGreaterThan(a,b)
Error using mustBeGreaterThan (line 19)
Value must be greater than the comparison value.

関連するトピック