プロパティのクラスとサイズの検証

プロパティのクラスとサイズ

MATLAB^® は検証関数を呼び出す前に、プロパティに対して定義された任意のクラスとサイズの検証を適用します。サイズまたはクラスの検証を定義するプロパティへの代入は、MATLAB オブジェクト配列への代入と類似しています。MATLAB はクラスとサイズの検証の要件を満たすため、代入の右辺にクラスとサイズの変換を適用できます。

詳細については、検証の順序およびプロパティの検証関数を参照してください。

プロパティのサイズの検証

プロパティ名に続いて、プロパティのサイズを行、列、追加次元として指定します。

classdef MyClass
   properties
      Prop(dim1,dim2,...) = defaultValue
   end
end

代入とサイズの検証

このクラスは Location プロパティのサイズを 1 行 3 列として定義します。このプロパティに代入される値はそのサイズに準拠しているか、そのサイズに変換可能でなければなりません。

classdef ValidateProps
   properties
      Location(1,3)
   end
end

MATLAB によって代入された暗黙的な既定値 [0 0 0] は指定サイズに準拠しています。

a = ValidateProps

a = 

  ValidateProps with properties:

    Location: [0 0 0]

MATLAB はスカラーを Location プロパティに代入するときにスカラー拡張を適用します。

a = ValidateProps;
a.Location = 1

a = 

  ValidateProps with properties:

    Location: [1 1 1]

MATLAB は列を行に変換してサイズ指定に一致させます。

col = [1;1;1]

a.Location = col

a = 

  ValidateProps with properties:

    Location: [1 1 1]

サイズ指定でのコロン

サイズ指定でのコロンは、対応する次元の長さに制限がないことを意味します。たとえば、このクラスの Label プロパティにはあらゆる長さの値を代入できます。

classdef ValidateProps
   properties
      Label(1,:)
   end
end

a = ValidateProps;
a.Label = 'Click to Start'

a = 

  ValidateProps with properties:

    Label: 'Click to Start'

サイズの検証を定義するプロパティへの代入は、同等のインデックス付き配列の代入と同じルールに従います。多次元配列のインデックス付け動作の詳細については、基本的な演算で互換性のある配列サイズを参照してください。

プロパティのクラスの検証

プロパティのクラスを定義すると、コードのプロパティに代入された値をテストする必要性を減らすことができます。一般的に、プロパティに代入される値は、指定されたクラスであるか、指定されたクラスに変換可能でなければなりません。このルールが適用されないのは、サブクラスの場合です。検証の一部としてユーザー定義クラスを指定すると、そのクラスのサブクラスはエラーなしで検証にパスしますが、変換されません。

プロパティごとに 1 つのクラスのみを指定できます。mustBeNumeric または mustBeInteger のような検証関数を使用して、プロパティをより広範なカテゴリのクラスに制限します。検証関数の詳細については、プロパティの検証関数を参照してください。

任意の MATLAB クラス、または MATLAB でサポートされる、Java^® クラスおよび COM クラス以外の外部定義クラスを使用することができます。

プロパティ定義ブロックで、プロパティ名の後にクラス名とオプションのサイズ指定を入力します。

classdef MyClass
   properties
      Prop ClassName = defaultValue
   end
end

既定値を指定しない場合、MATLAB は指定クラスの空のオブジェクトをプロパティに代入します。サイズとクラスを定義すると、MATLAB は、そのサイズとクラスの要件を満たすプロパティの既定値を作成しようとします。

MATLAB は、引数なしでクラスコンストラクターを呼び出し、既定値を作成します。クラスが入力引数なしで呼び出される場合、指定されたサイズのオブジェクトを返すコンストラクターを保持しなければなりません。または、プロパティサイズの制限を満たすように、プロパティには既定値を指定しなければなりません。詳細については、サイズおよびクラスごとの既定値を参照してください。

クラスの検証の使用

PropsWithClass クラスは、クラス定義をもつ 2 つのプロパティを定義します。

Number — 値はクラス double であるか、double に変換可能でなければならない。
Today — 値はクラス string であるか、string に変換可能でなければならない。既定値は、関数 datetime によって返される現在の日付です。

classdef PropsWithClass
   properties
      Number double
      Today string = datetime("today")
   end
end

PropsWithClass クラスのオブジェクトを作成します。

p = PropsWithClass

p = 

  PropsWithClass with properties:

    Number: []
     Today: "09-Jun-2022"

MATLAB は適合するクラスをプロパティのクラスに変換します。たとえば、Number プロパティに配列 unint8 値を代入します。

p.Number = uint8(5);
disp(class(p.Number))

ans =

double

uint8 値は double に変換できるため、その uint8 値を Number プロパティに代入できます。

クラスの検証を使用するプロパティに非適合の値を代入すると、エラーが発生します。

p.Number = datetime("today");

Error setting property 'Number' of class 'PropsWithClass':
Value must be double or be convertible to double.

検証用のユーザー定義クラス

プロパティに代入された値を制御するクラスを定義することができます。列挙クラスを使用すると、名前のあいまい一致でプロパティ値を文字ベクトルまたは string スカラーに設定することができます。

たとえば、3 速の機械式ポンプを表すクラスがあるとします。3 つの流量を表す列挙クラスを定義できます。

classdef FlowRate < int32
   enumeration
      Low    (10)
      Medium (50)
      High   (100)
   end
end

Pump クラスには、現在の流量を 1 分あたりのガロンで返すメソッドがあります。Speed プロパティを FlowRate クラスとして定義します。

classdef Pump
   properties
      Speed FlowRate
   end
   methods
      function getGPM(p)
         if isempty(p.Speed)
            gpm = 0;
         else
            gpm = int32(p.Speed);
         end
         fprintf('Flow rate is: %i GPM\n',gpm);
      end
   end
end

あいまいなテキストを使用して Speed プロパティを設定できます。

p = Pump;
p.Speed = 'm'

p = 

  Pump with properties:

    Speed: Medium

プロパティから数値を取得できます。

getGPM(p)

Flow rate is: 50 GPM

列挙クラスの詳細については、列挙クラスの定義を参照してください。

整数クラスの検証

MATLAB は複数の整数クラスをサポートします (整数を参照)。ただし、プロパティを整数クラスに制限すると、整数のオーバーフローが発生することがあります。結果の値は整数の範囲の最大値または最小値で飽和することがあります。

整数のオーバーフローが発生する場合、プロパティに代入される値は代入ステートメントの右辺からの値とは異なる値である可能性があります。

たとえば、プロパティ値をスカラーの uint8 に制限するとします。

classdef IntProperty
   properties
      Value(1,1) uint8
   end
end

数値を Value プロパティに代入すると、数値は実質的に uint8 にキャストされますが、範囲外の値としてのエラーにはなりません。

a = IntProperty;
a.Value = -10;
disp(a.Value)

Value プロパティへの代入は、配列のインデックス付き代入と同等です。代入値が uint8 で表せる値の範囲外にある場合、MATLAB は値を uint8 で表せる最も近い値に設定します。

a = uint8.empty;
a(1) = -10

a =

  uint8

   0

整数のオーバーフローが発生する可能性を回避するには、整数クラスではなく意図する範囲に値を制限する検証関数の組み合わせを使用します。

classdef IntProperty
   properties
      Value(1,1) {mustBeInteger, mustBeNonnegative,...
         mustBeLessThan(Value,256)}
   end
end

uint8 クラスによる代入値の変換がないため、検証関数が範囲外の値をキャッチし、適切なエラーをスローします。

a = IntProperty;
a.Value = -10;

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

サイズおよびクラスごとの既定値

クラス定義で代入するプロパティの既定値は、指定された検証に準拠しなければなりません。

暗黙的な既定値

クラス定義で既定値を指定しない場合、MATLAB は既定値を暗黙的に定義します。この表では、サイズとクラスで MATLAB クラスの暗黙的な既定値が決定される方法を示します。

サイズ	クラス	MATLAB で代入される暗黙的な既定値
`(m,n)`	任意の数値	指定したクラスのゼロの m 行 n 列の配列。
`(m,:)` または `(:,n)`	任意のクラス	指定したクラスの m 行 0 列または 0 行 n 列の配列。
`(m,n)`	`char`	空白の m 行 n 列の文字配列。
`(m,n)`	`cell`	各セルに 0 行 0 列の double が含まれる m 行 n 列の cell 配列。
`(m,n)`	`struct`	m 行 n 列の `struct`
`(m,n)`	`string`	m 行 n 列の `string`
`(m,n)`	列挙クラス	クラスで定義された最初の列挙メンバー。
`(1,1)`	`function_handle`	実行時エラー — クラスで既定値を定義してください。

非ゼロおよび明示的なサイズの指定に対して暗黙的な既定値を決定するため、MATLAB は既定のクラスコンストラクターを呼び出し、コンストラクターの呼び出しから返されるインスタンスを使用して指定されたサイズの配列を作成します。クラスで既定のコンストラクター (つまり、引数なしで呼び出されたコンストラクター) がサポートされない場合、MATLAB は検証を含むクラスをインスタンス化するときにエラーをスローします。

指定されたサイズにゼロまたは無制限 (:) の次元がある場合、MATLAB は、無制限次元をゼロに設定した空の配列の既定値を作成します。

異種混合配列の場合、MATLAB は getDefaultScalarElement メソッドを呼び出して既定のオブジェクトを取得します。