プロパティ値の検証

クラス定義でのプロパティの検証

MATLAB^® プロパティ検証では、プロパティ値に特定の制限を課すことができます。検証を使用して、プロパティ値のクラスとサイズを制約することが可能です。また、関数を使用して、プロパティ値が準拠しなければならない基準を設定することもできます。MATLAB では一連の検証関数が定義されており、ユーザー独自の検証関数を記述することが可能です。

クラス定義でのプロパティ検証の使用はオプションです。

プロパティ検証の追加情報

プロパティ検証の詳細については、プロパティのクラスとサイズの検証、プロパティの検証関数、およびプロパティ検証へのメタデータインターフェイスを参照してください。

検証構文

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

Properties block with validation syntax

プロパティ検証には以下のすべてが含まれます。

サイズ — 各次元の長さ。正の整数またはコロンで指定します。コロンは、その次元で任意の長さが許可されることを示します。プロパティに代入される値は、指定されたサイズに準拠するか、指定されたサイズに適合しなければなりません。詳細については、プロパティのサイズの検証を参照してください。
クラス — 単一の MATLAB クラスの名前。プロパティに代入される値は、指定されたクラスであるか、指定されたクラスに変換可能でなければなりません。任意の MATLAB クラス、または MATLAB でサポートされる、Java^® クラスおよび COM クラス以外の外部定義クラスを使用します。詳細については、プロパティのクラスの検証を参照してください。
関数 — 検証関数名のコンマ区切りリスト。MATLAB は、必要に応じてクラスとサイズの変換を適用した後、プロパティに代入された値を各検証関数に渡します。検証に失敗した場合、検証関数はエラーをスローしますが、値は返しません。詳細については、プロパティの検証関数を参照してください。
MATLAB 検証関数の一覧については、プロパティの検証関数を参照してください。

プロパティ検証の使用

ユーザーコードでプロパティに代入する値を制御するには、パブリックプロパティに対するプロパティ検証を使用してください。

プロパティ値を固定された識別子セットに制限する場合は、それらの識別子の列挙クラスを作成し、プロパティをこのクラスに制限します。列挙クラスの詳細については、列挙クラスの定義を参照してください。

プロパティ検証には MATLAB の型変換ルールが適用されます。たとえば、MATLAB は、ある数値型を別の数値型に強制変換できます。そのため、プロパティ値を特定の数値型 (double など) に制限しても、他の数値型をプロパティに代入できなくなることはありません。

プロパティに必ず特定の型の値のみが割り当てられるようにするには、目的の型変換のみをサポートする型にプロパティを制限するか、またはプロパティ型を指定する代わりに、検証関数を使用してプロパティに許可されるクラスを厳密に指定します。MATLAB は、検証関数を実行する前に、型指定を評価します。詳細については、検証の順序を参照してください。

有効な既定値の指定

プロパティに割り当てられた既定値が、指定された検証の制約を満たしていることを確認してください。既定値を指定しないと、MATLAB では、指定されたクラスの空オブジェクトが割り当てられるか、サイズ制限で空の既定値を使用できない場合は、既定のコンストラクターを呼び出して、既定値が作成されます。既定のコンストラクターは、正しいサイズのオブジェクトを返さなければなりません。

プロパティ検証を使用するサンプルクラス

ValidateProps クラスは検証用の 3 つのプロパティを定義します。

classdef ValidateProps
   properties
      Location(1,3) double {mustBeReal, mustBeFinite}
      Label(1,1) string {mustBeMember(Label,["High","Medium","Low"])} = "Low"
      State(1,1) matlab.lang.OnOffSwitchState
   end
end

Location は、値が実数の有限数である double クラスの 1 行 3 列の配列でなければなりません。
Label は、"High"、"Medium"、"Low" のいずれかの string スカラーでなければなりません。
State は、matlab.lang.OnOffSwitchState クラスの列挙メンバー (off または on) でなければなりません。

インスタンス化での検証

ValidateProps クラスのオブジェクトを作成すると、暗黙的および明示的な既定値について検証が実行されます。

a = ValidateProps

a = 

  ValidateProps with properties:

    Location: [0 0 0]
       Label: "Low"
       State: off

オブジェクトを作成すると、MATLAB で次が行われます。

Location プロパティ値を [0 0 0] に初期化してサイズとクラスの要件を満たす。
Label プロパティを既定値 "Low" に設定する。既定値は許可された値セットのメンバーでなければなりません。string の空の既定値は、エラーの原因になることがあります。
State プロパティを matlab.lang.OnOffSwitchState クラスで定義された off 列挙メンバーに設定する。

MATLAB が既定値を選択する方法の詳細については、サイズおよびクラスごとの既定値を参照してください。

検証の順序

クラスの定義で指定される既定値を含め、値がプロパティに代入されるとき、MATLAB は次の順序で検証を実行します。

クラスの検証 — この検証では、クラス char から string へなど、異なるクラスへの変換が発生することがあります。プロパティへの代入は、配列用の MATLAB 変換ルールに従います。
サイズの検証 — この検証では、スカラー拡張や、列ベクトルから行ベクトルへの変換など、サイズの変換が発生することがあります。サイズの検証を指定するプロパティへの代入は、任意の MATLAB 配列への代入と同じように動作します。インデックス付き代入の詳細については、配列インデックス付けを参照してください。
検証関数 — MATLAB はクラスとサイズの検証結果を左から右の順序で各検証関数に渡します。すべての検証関数が呼び出される前にエラーが発生して検証プロセスが終了することがあります。
set メソッド — プロパティに対して set メソッドが定義されている場合、MATLAB はプロパティの set メソッドを呼び出す前に、プロパティ検証を実行します。プロパティの set メソッドまたは get メソッド内でプロパティへの代入を行っても、再検証は適用されません。多くの場合、プロパティの set メソッドは、プロパティ検証を使用して置換できます。

プロパティ検証エラー

ValueProp クラスはサイズ、クラスおよび関数の検証を使用して、Value プロパティへの代入が非負の double のスカラーであることを確認します。

classdef ValueProp
   properties
      Value(1,1) double {mustBeNonnegative} = 0
   end
end

このステートメントは、cell 配列をプロパティに代入しようとしています。この代入はクラスの検証に違反します。

a.Value = {10,20};

Error setting property 'Value' of class 'ValueProp':
Invalid data type. Value must be double or be convertible to double.

このステートメントは、1 行 2 列の double の配列をプロパティに代入しようとしています。この代入は、サイズの検証に違反します。

a.Value = [10 20];

Error setting property 'Value' of class 'ValueProp':
Size of value must be scalar.

このステートメントは、double のスカラーをプロパティに代入しようとしています。この代入は非負の数を必要とする関数の検証に失敗します。

a.Value = -10;

Error setting property 'Value' of class 'ValueProp':
Value must be nonnegative.

この検証プロセスは、最初のエラーが発生した時点で終了します。

抽象プロパティの検証

抽象プロパティに対するプロパティ検証を定義できます。検証は、プロパティを実装するすべてのサブクラスに対して適用されます。ただし、サブクラスは、そのプロパティの実装に対していかなる検証も使用することができません。複数のクラスからプロパティの検証を継承する場合、1 つのスーパークラスに含まれる単一の抽象プロパティによってのみ検証を定義できます。いずれのスーパークラスでも、プロパティを具象として定義することはできません。

検証の変更時に更新されないオブジェクト

クラスのオブジェクトが存在する間にプロパティ検証を変更しても、MATLAB は新しい検証を既存のプロパティ値に適用しません。ただし、MATLAB は既存のオブジェクトのプロパティへの代入を行うときに新しい検証を適用します。

読み込み操作中の検証

オブジェクトを MAT ファイルに保存するとき、MATLAB はオブジェクトとともにプロパティのすべての非既定値を保存します。MATLAB はオブジェクトを読み込むときに、新たに作成されるオブジェクトでこれらのプロパティ値を復元します。

クラス定義によりプロパティ検証が変更され、読み込まれたプロパティ値が有効でなくなってしまう場合、MATLAB は現在そのプロパティに定義されている既定値を代用します。ただし、関数 load は既定値を現在のクラス定義から代入する前に発生する検証エラーを非表示にします。そのため、検証エラーは読み込み操作中に静的に無視されます。

この動作を説明するため、この例では MonthTemp クラスのオブジェクトの作成、保存、読み込みを行います。このクラスは、AveTemp プロパティを cell 配列に制限します。

classdef MonthTemp
   properties
      AveTemp cell 
   end
end

MonthTemp オブジェクトを作成し、値を AveTemp プロパティに代入します。

a = MonthTemp;
a.AveTemp = {'May',70};

save を使用してオブジェクトを保存します。

save TemperatureFile a

プロパティ定義を編集して、AveTemp プロパティの検証クラスを cell 配列から containers.Map に変更します。

classdef MonthTemp
   properties
      AveTemp containers.Map
   end
end

新しいクラス定義で MATLAB パス上に保存したオブジェクトを読み込みます。プロパティ値は containers.Map オブジェクトでなければならないという現在の要件に cell 配列 {'May',70} が適合しないため、MATLAB は保存された値を AveTemp プロパティに代入できません。MATLAB は cell 配列を containers.Map に変換できません。

この不適合に対処するために、MATLAB は読み込まれたオブジェクトの AveTemp プロパティを現在の既定値である空の containers.Map オブジェクトに設定します。

load TemperatureFile a
 a.AveTemp

ans = 

  Map with properties:

        Count: 0
      KeyType: char
    ValueType: any

保存された値が無効になったため、読み込まれたオブジェクトの値は AveTemp プロパティに代入された値とは異なります。しかし、読み込みプロセスでは検証エラーが非表示になります。

クラス定義を変更してオブジェクトを再読み込みする際のデータの損失を回避するには、保存された値が現在のプロパティ検証の要件を満たせるようにする loadobj メソッドまたはクラスコンバーターメソッドを実装します。

オブジェクトの保存と読み込みの詳細については、オブジェクトの保存と読み込みのプロセスを参照してください。