Main Content

本页的翻译已过时。点击此处可查看最新英文版本。

属性验证函数

MATLAB 验证函数

MATLAB® 定义了用于属性验证的函数。这些函数支持验证的常用模式,并提供描述性错误消息。下表对 MATLAB 验证函数进行了分类并描述了它们的用法。

数值属性

名称

含义

对输入调用的函数

mustBePositive(value)

value > 0

gtisrealisnumericislogical

mustBeNonpositive(value)

value <= 0

geisrealisnumericislogical

mustBeNonnegative(value)

value >= 0

geisrealisnumericislogical

mustBeNegative(value)

value < 0

ltisrealisnumericislogical

mustBeFinite(value)

value 中不含 NaNInf 元素。

isfinite

mustBeNonNan(value)

value 中不含 NaN 元素。

isnan

mustBeNonzero(value)

value ~= 0

eqisnumericislogical

mustBeNonsparse(value)

value 中不含稀疏元素。

issparse

mustBeReal(value)

value 没有虚部。

isreal

mustBeInteger(value)

value == floor(value)

isrealisfinitefloorisnumericislogical

mustBeNonmissing(value)

value 不能包含缺失值。

ismissing

与其他值的比较

名称

含义

对输入调用的函数

mustBeGreaterThan(value,c)

value > c

gtisscalarisrealisnumericislogical

mustBeLessThan(value,c)

value < c

ltisrealisnumericislogical

mustBeGreaterThanOrEqual(value,c)

value >= c

geisrealisnumericislogical

mustBeLessThanOrEqual(value,c)

value <= c

leisrealisnumericislogical

数据类型

名称

含义

对输入调用的函数

mustBeA(value,classnames)

value 必须为特定类。

使用类定义关系

mustBeNumeric(value)

value 必须为数值。

isnumeric

mustBeNumericOrLogical(value)

value 必须为数值或逻辑值。

isnumericislogical

mustBeFloat(value)

value 必须为浮点数组。

isfloat

mustBeUnderlyingType(value,typename)

value 必须具有指定的基础类型。

isUnderlyingType

大小

名称

含义

对输入调用的函数

mustBeNonempty(value)

value 不为空。

isempty

mustBeScalarOrEmpty(value)value 必须为标量或为空。

isscalarisempty

mustBeVector(value)value 必须为向量。

isvector

成员关系和范围

名称

含义

对输入调用的函数

mustBeMember(value,S)

value 的所有成员都可在 S 中找到。

ismember

mustBeInRange(value,lower,upper,boundflags)value 必须在范围内。

gtgeltle

文本

名称

含义

对输入调用的函数

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 属性限制为仅 uint8uint16 值,从而排除子类并且不允许从其他数值类进行转换。预定义的验证函数 mustBeInRange 则限制了允许的值范围。

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

当您创建 ImgData 类的实例时,MATLAB 会验证默认值是否为 0...255 范围内的 uint8uint16 值,且不为空。请注意,默认值必须与赋给该属性的任何其他值一样,满足验证要求。

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.

要了解相关函数,请参阅 mustBeIntegermustBeNumericmustBePositive

添加对验证函数的支持

要为您的类对象添加对 MATLAB 验证函数的支持,可以将验证函数所用到的函数实现为类的方法。要确定应为每个函数实现哪些方法,请参阅 MATLAB 验证函数的表中所列验证函数的参考页。

例如,假设您想为您的类添加对 mustBeGreaterThan 验证函数的支持。重载这些 MATLAB 函数作为类中的方法:

  • isreal - 始终返回逻辑值 true,因为 mustBeGreaterThan 不支持复数。

  • gt - 根据 mustBeGreaterThan 的要求,比较中的第二个对象必须为标量。

通过 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.

相关主题