属性验证函数

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`
`mustBeSparse(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` 必须为数值或逻辑值。	`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` 必须为字符串数组、字符向量或字符向量元胞数组。	不适用
`mustBeTextScalar(value)`	`value` 必须为一段文本。	不适用
`mustBeValidVariableName(varname)`	`varname` 必须为有效的变量名称。	`isvarname`

使用函数验证属性

使用类定义中的属性验证函数对属性值施加特定限制。验证函数接受潜在的属性值作为参量，如果该值不满足函数所施加的特定要求，则发出错误。

在验证过程中，MATLAB 将值传递给类定义中列出的每个验证函数。MATLAB 从左到右调用每个函数，并在遇到第一个错误时发出错误警告。传递给验证函数的值是在设定类和大小时应用任意转换之后的结果。有关类和大小验证的详细信息，请参阅Property Class and Size Validation。

有关 MATLAB 验证函数的列表，请参阅MATLAB 验证函数。

验证函数语法

将验证函数指定为一组以逗号分隔的函数名称或含参函数调用（括在花括号内）。

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

MATLAB 将可能的属性值隐式传递给验证函数。但是，如果验证函数除可能的属性值之外还需要输入参量，则必须包括属性和附加参量。附加参量必须为字面值，不能引用变量。字面值采用非符号表示形式，如数字和文本。

以函数 mustBeGreaterThan 为例。它需要一个界限值作为输入参数。此验证函数要求属性值必须大于此界值。

将属性作为第一个参量传递。使用属性名称，但不要用引号将名称括起来。此属性定义将 Prop 限制为大于 10 的值。

properties
   Prop {mustBeGreaterThan(Prop,10)}
end

使用验证函数

以下类为每个属性指定验证函数。

Data 必须为有限数值。
Interp 必须为列出的三个选项之一。为此属性指定一个默认值以满足此要求。

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

对 char 向量的赋值不会产生错误，因为 MATLAB 会将 char 向量转换为 double 类。

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

使用枚举类，它支持不精确匹配且不区分大小写。

通过枚举类实现不精确匹配

使用枚举类进行属性验证具有以下优点：

对于明确字符向量或字符串标量，可进行不精确、不区分大小写的匹配
将不精确匹配转换为正确值

例如，假设您为 Interp 属性验证定义了 InterpMethod 枚举类。

classdef InterpMethod
   enumeration
      linear
      cubic
      spline
   end
end

更改 Interp 属性验证以使用 InterpMethod 类。

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)
    if ~(isa(a,'uint8') || isa(a,'uint16'))
        error("Value of Data property must be uint8 or uint16 data.")
    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 of Data property must be 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。