参数验证简介

函数参数验证是一种对函数输入参数声明特定限制的方法。使用参数验证，您可以约束函数输入值的类、大小和其他方面，而无需在函数体中编写代码来执行这些测试。

函数参数验证是声明性的，这使得 MATLAB^® 桌面工具能够通过检查特定代码块来提取关于函数的信息。通过声明输入参数的要求，您可以消除繁琐的参数检查代码，并提高代码的可读性、稳健性和可维护性。

函数参数验证语法简化了定义可选参数、重复参数和名称-值参数的过程。该语法还使您能够以一致的方式定义默认值。

何时使用参数验证

在函数定义中，您可以选择是否使用函数参数验证。如果函数可由任何代码调用，并且在执行函数代码之前必须确定输入的有效性，则参数验证能起到很大帮助。对于那些为他人使用而设计的函数，如能对参数输入施加适当限制，并允许基于函数输入返回特定错误消息，也可使用户受益。

arguments 代码块语法

函数在以关键字 arguments 和 end 起止的代码块中定义参数验证。如果使用，arguments 代码块必须在函数的第一个可执行代码行之前开始。

您可以在一个函数中使用多个 arguments 代码块，但是，所有这些代码块必须出现在不属于 arguments 代码块的代码之前。

下面代码中突出显示的部分展示了参数验证的语法。

函数参数声明可以包括以下任何一种限制：

您还可以在该参数的函数验证声明中为输入参数定义默认值。默认值必须满足对该参数声明的限制。

A(indices) = value

参数验证示例

此 arguments 代码块指定三个输入的大小和类。

function out = myFunction(A, B, C)   
    arguments
        A (1,1) string 
        B (1,:) double
        C (2,2) cell
    end

    % Function code
    ...
end

在此函数中，变量必须满足以下验证要求：

function forwardSpeed(a,b,c)
    arguments
        a double
        b char
        c SpeedEnum
    end

    % Function code
    disp(class(a))
    disp(class(b))
    disp(class(c))
end

classdef SpeedEnum < int32
    enumeration
        Full   (100)
        Half   (50)
        Stop   (0)
    end
end

forwardSpeed(int8(4),"A string",'full')

double
char
SpeedEnum

function myInterp(x,v,method)
    arguments
        x (1,:) {mustBeNumeric,mustBeReal}
        v (1,:) {mustBeNumeric,mustBeReal,mustBeEqualSize(v,x)}
        method (1,:) char {mustBeMember(method,{'linear','cubic','spline'})} = 'linear'
    end
    % Function code
    ....
end

% Custom validation function
function mustBeEqualSize(a,b)
    % Test for equal size
    if ~isequal(size(a),size(b))
        eid = 'Size:notEqual';
        msg = 'Size of first input must equal size of second input.';
        throwAsCaller(MException(eid,msg))
    end
end

参数的种类

函数参数验证可以声明四种参数。函数可以定义四种参数中的任何一种，但参数必须按照以下顺序定义：

必需和可选位置参数

位置参数必须以特定顺序传递给函数。参数列表中传递的值的位置必须对应于参数在 arguments 代码块中声明的顺序。arguments 代码块中的所有参数名称必须唯一。

调用函数时，arguments 代码块中的位置参数为必需，除非此参数定义了默认值。在参数声明中指定默认值会使位置参数成为可选参数，因为 MATLAB 可以在函数调用中没有传递值时使用默认值。

默认值可以是常量，也可以是结果满足参数声明的表达式。表达式可以引用在 arguments 代码块中在该表达式之前声明的参数，但无法引用在它后面声明的参数。

MATLAB 仅在函数调用不包含某参数时才计算其默认值表达式。

所有可选参数都必须位于 arguments 代码块中的所有必需参数后。例如，在此参数代码块中，maxval 和 minval 具有默认值，因此是可选的。

function myFunction(x,y,maxval,minval)
    arguments
        x (1,:) double
        y (1,:) double
        maxval (1,1) double = max(max(x),max(y))
        minval (1,1) double = min(min(x),min(y))
    end

    % Function code
    ....
end

您可以使用以下任意语法调用此函数：

myFunction(x,y,maxval,minval) 
myFunction(x,y,maxval) 
myFunction(x,y) 

如果必须在函数调用中填充某可选位置参数的位置以标识其后的参数，则该可选位置参数变为必需参数。在上述实例中，这相当于：如果要指定 minval 的值，必须指定 maxval 的值。

function c = f(~)
    arguments
        ~
    end

    % Function code
end

c = f 

c = f(2)

function c = f(~,x)
    arguments
        ~
        x
    end

    % Function code
    ...
end

c = f(2,3)

重复参数

重复参数是可以重复指定为输入参数的位置参数。在包含 Repeating 属性的 arguments 代码块中声明重复参数。

arguments (Repeating)
    arg1
    arg2
    ...
end

函数只能有一个 Repeating arguments 代码块，其中可以包含一个或多个重复参数。

如果函数定义了 Repeating arguments 代码块，则调用该函数时，此代码块中的参数可以一次也不出现，也可以全体出现一次或多次。如果对函数的调用包含重复参数，则每次重复都必须包含 Repeating arguments 代码块中的所有参数。

例如，如果 Repeating arguments 代码块定义参数 x 和 y，则每次重复必须同时包含 x 和 y。

重复参数不能指定默认值，因此不能为可选项。但是，您可以不带任何重复参数调用函数。

重复参数在函数中的声明顺序必须在位置参数之后、名称-值参数之前。您不能在 Repeating 代码中指定名称-值参数。有关名称-值参数的信息，请参阅名称-值参数。

在函数中，每个重复参数构成一个元胞数组，其中包含的元素数等于在函数调用中传递的重复次数。验证应用于该元胞数组的每个元素。如果调用函数时该参数的出现次数为零，则元胞数组的大小为 1×0。也就是说，它为空。

例如，以下函数声明一个重复参数代码块，其中包含三个参数 x、y 和 option。

function [xCell,yCell,optionCell] = fRepeat(x,y,option)
    arguments (Repeating)
        x double
        y double
        option {mustBeMember(option,["linear","cubic"])}
    end
    
    % Function code
    % Return cell arrays
    xCell = x;
    yCell = y;
    optionCell = option;
end

调用此函数时，您可以不带输入，也可以将三个输入重复多次。MATLAB 为每个参数创建一个元胞数组，其中包含为该参数传递的所有值。以下对 fRepeat 的调用将这三个重复参数全体传递了两次。

[xCell,yCell,optionCell] = fRepeat(1,2,"linear",3,4,"cubic")

xCell =

  1×2 cell array

    {[1]}    {[3]}


yCell =

  1×2 cell array

    {[2]}    {[4]}


optionCell =

  1×2 cell array

    {["linear"]}    {["cubic"]}

以下函数声明 Repeating arguments 代码块，从而允许重复输入参数 x 和 y。在函数体中，指定为重复参数的值包含在元胞数组 x 和 y 中。此示例交错 x 和 y 中的值，以匹配 plot 函数的必需输入：plot(x1,y1,…)。

function myPlotRepeating(x,y)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
    end

    % Function code
    % Interleave x and y
    z = reshape([x;y],1,[]);

    % Call plot function
    if ~isempty(z)
        plot(z{:});
    end
end

使用重复的输入参数对来调用此函数。

x1 = 1:10;
y1 = sin(x1);
x2 = 0:5;
y2 = sin(x2);
myPlotRepeating(x1,y1,x2,y2)

function f(a, b, varargin)
    arguments
        a uint32
        b uint32
    end
    arguments (Repeating)
        varargin
    end
    
    % Function code
    ...
end

名称-值参数

名称-值参数将名称与传递给函数的值相关联。名称-值参数：

使用圆点表示法在 arguments 代码块中声明名称-值参数以定义结构体的字段。例如，名为 NameValueArgs 的结构体定义两个名称-值参数 Name1 和 Name2。您可以使用任何有效的 MATLAB 标识符作为结构体名称。

arguments
    NameValueArgs.Name1
    NameValueArgs.Name2
end

结构体名称必须出现在函数签名中。

function myFunction(NameValueArgs)

使用名称-值结构体中的字段名称调用该函数。

myFunction(Name1=value1,Name2=value2)

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。这两种语法在以后的版本中都有效。

函数签名中使用的结构体名称是函数工作区中包含传递给该函数的名称和值的结构体的名称。

function result = myFunction(NameValueArgs)
    arguments
        NameValueArgs.Name1
        NameValueArgs.Name2
    end

    % Function code
    result = NameValueArgs.Name1 * NameValueArgs.Name2;
end

r = myFunction(Name1=3,Name2=7)

r =

    21

当不存在多义性时，名称-值参数支持部分名称匹配。例如，将 LineWidth 和 LineStyle 定义为其两个名称-值参数的函数接受 LineW 和 LineS，但使用 Line 会导致错误。一般情况下，推荐使用全名，以提高代码可读性和避免意外行为。

function myRectangle(width,height,options)
    arguments
        width double
        height double
        options.LineStyle (1,1) string = "-"
        options.LineWidth (1,1) {mustBeNumeric} = 1
    end

    % Function code
    ...
end

myRectangle(4,5)
myRectangle(4,5,LineStyle=":",LineWidth=2)
myRectangle(4,5,LineWidth=2,LineStyle=":")
myRectangle(4,5,LineStyle=":")
myRectangle(4,5,LineWidth=2)

myRectangle(4,5,"LineStyle",":","LineWidth",2)
myRectangle(4,5,"LineWidth",2,"LineStyle",":")

function myLinLog(x,y,scale)
    arguments(Repeating)
        x (1,:) double
        y (1,:) double
    end
    arguments
        scale.PlotType (1,1) string
    end
    z = reshape([x;y],1,[]);
    if isfield(scale,"PlotType")
        if scale.PlotType == "lin"
            plot(z{:})
        elseif scale.PlotType =="log"
            loglog(z{:})
        end
    end
end

myLinLog(1:5,1:5)
myLinLog(1:5,1:5,1:10,1:100:1000)
myLinLog(1:5,1:5,1:10,1:100:1000,PlotType="log")

myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")

function myRectangle(width,height,lineOptions,fillOptions)
    arguments
        width double
        height double
        lineOptions.LineStyle (1,1) string = "-"
        lineOptions.LineWidth (1,1) {mustBeNumeric} = 1
        fillOptions.Color string
        fillOptions.Pattern
    end

    % Function Code
    ...
end

名称-值参数的稳健处理

在函数中实现名称-值参数的最佳做法是在参数块中定义它们。使用参数块就无需编写自己的代码来解析名称-值参数，参数块还有助于为 R2021a 中引入的 "name",value 语法和 name=value 语法实现稳健的参数解析。

myFunction(data,"allow-empty",true)

function mySignal(tag,unit,opts)
    arguments
        tag = "0"
        unit = "ampere"
        opts.Magnifier {mustBeMember{opts.Magnifier,["small","medium","big"]}}
    end
end

mySignal("Mag","coulomb")

function mySignal(tag,unit,opts)
    arguments
        tag
        unit = "ampere"
        opts.Magnifier {mustBeMember{opts.Magnifier,["small","medium","big"]}}
    end
end

基于类属性的名称-值参数

MATLAB 提供了一个方便的函数语法，允许您使用类的公共属性作为名称-值参数的名称。要将类定义的所有可设置属性（即具有公共 SetAccess 的所有属性）指定为名称-值参数，请在 arguments 代码块中使用以下语法：

structName.?ClassName

一个函数只能使用一次 "structName.? ClassName" 语法。因此，即便使用不同的类和结构体名称，一个函数也只能定义一个从类中获取字段名称的名称-值结构体。

如果类通过属性验证来限制可以赋给属性的值，则函数会将验证应用于单独的名称-值参数。有关属性验证的信息，请参阅验证属性值。

例如，此函数有两个必需参数 x 和 y，并且接受 matlab.graphics.chart.primitive.Bar 类的任何公共属性的名称和值。

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

使用必需输入以及任何可设置属性的名称-值对组来调用此函数。

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="magenta",BarLayout="grouped")

在 R2021a 之前，将名称作为字符串或字符向量传递，并以逗号分隔名称和值。例如：

myBar(x,y,"FaceColor","magenta","BarLayout","grouped")

structName.?ClassName
structName.PropertyName (dim1,dim2,...) ClassName {fcn1,fcn2,...}

function myBar(x,y,propArgs)
    arguments
        x (:,:) double
        y (:,:) double
        propArgs.?matlab.graphics.chart.primitive.Bar
        propArgs.FaceColor {mustBeMember(propArgs.FaceColor,{'red','blue'})} = "blue"
    end
    propertyCell = namedargs2cell(propArgs);
    bar(x,y,propertyCell{:})
end

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="red",BarLayout="grouped")

类方法中的参数验证

在公共方法中，对方法输入参数进行验证很有用，因为对方法的调用可能不是源于类代码。您可以在具体类方法中使用函数参数验证，包括在抽象类中定义的具体方法。但是，抽象方法（并非由类实现的方法）无法定义 arguments 代码块。有关类方法的信息，请参阅方法和抽象类和类成员。

如果 classdef 文件包含在单独文件中定义的方法的方法原型，请在定义该方法的单独文件中包含 arguments 代码块。有关在单独的文件中定义方法的详细信息，请参阅在单独文件中定义方法。

子类方法不继承函数参数验证。在覆盖超类方法的子类方法中，您可以向子类方法添加与在超类方法中使用的相同参数验证。

句柄类析构函数方法无法使用参数验证。在包含 arguments 代码块的句柄子类中，名为 delete 的方法不会被视为析构函数。（换句话说，在销毁对象时，MATLAB 不调用它。）有关类析构函数方法的详细信息，请参阅句柄类析构函数。

参数验证的顺序

在调用函数时，MATLAB 按照输入参数在 arguments 代码块中的声明顺序从上往下验证输入参数。上一个参数完全验证后，才会继续验证下一个参数。这就确保引用较早声明的参数时，使用的是经过验证的值。在第一次验证失败时，函数会引发错误。

经过验证的值可能不同于调用函数时作为输入传递的原始值。例如，此函数将输入声明为类 uint32 值。第三个输入声明指定了一个默认值，该值等于前两个输入的乘积。

function c = f(a, b,c)
    arguments
        a uint32
        b uint32
        c uint32 = a .* b
    end

    % Function code
    ...
end

如果使用其他数值类（例如 double）的输入来调用函数，则输入会被转换为 uint32。

c = f(1.8,1.5)

由于在函数调用中没有指定可选输入参数 c，因此在将 a 和 b 转换为 uint32 值后，MATLAB 会计算默认值并将其赋给 c。在本例中，两个输入的转换结果均为值 2。因此，a 和 b 的乘积是 4。

c =

  uint32

   4

如果您为第三个输入指定值，则该函数会为 c 赋值，并且不会计算默认值表达式。

c = f(1.8,1.5,25)

c =

  uint32

   25

避免类和大小转换

在验证过程中，MATLAB 在调用任何验证函数之前，会先应用类验证，然后应用大小验证。如果默认值用于函数调用中省略的可选输入，则在应用验证过程中的任何步骤之前，会先将该值赋给参数。

当传递给函数的参数值与验证所要求的类和大小不匹配时，MATLAB 会尽可能将该值转换为声明的类和大小。然而，转换可能不是所需的行为。

以下是 MATLAB 可以执行的一些转换示例。

为了满足数值类限制，支持以下功能：

为了满足大小限制，支持以下功能：

要从输入参数验证中去除 MATLAB 执行的标准转换，请使用验证函数，而不是类和大小限制。对验证函数的调用不会返回值，也无法更改输入参数的值。

例如，此函数将第一个输入限制为 double 类的任意大小的二维数组。第二个输入必须为任何类的 5×3 数组。

function f(a, b)
    arguments
        a (:,:) double
        b (5,3)
    end

    % Function code
    ...
end

由于存在标准 MATLAB 类型转换和标量扩展，您可以使用以下输入调用此函数，而不会收到验证错误。

f('character vector',144)

默认情况下，MATLAB 将字符向量的元素转换为其等效数值，并应用标量扩展以基于标量值 144 创建一个 5×3 数组。

使用专用验证函数可以提供更具体的输入参数验证。例如，此函数定义专用验证函数，用于代替第一个和第二个参数的类和大小设定。这些局部函数帮助您避免输入值转换。

function fCustomValidators(a,b)
    arguments
        a {mustBeOfClass(a,'double'), mustBeDims(a,2)}
        b {mustBeEqualSize(b,a)}
    end

    % Function code
    ...
end

% Custom validator functions
function mustBeOfClass(input,className)
    % Test for specific class name
    cname = class(input);
    if ~strcmp(cname,className)
        eid = 'Class:notCorrectClass';
        msg = ['Input must be of class ', cname];
        throwAsCaller(MException(eid,msg))
    end
end

function mustBeEqualSize(a,b)
    % Test for equal size
    if ~isequal(size(a),size(b))
        eid = 'Size:notEqual';
        msg = 'Inputs must have equal size.';
        throwAsCaller(MException(eid,msg))
    end
end

function mustBeDims(input,numDims)
    % Test for number of dimensions    
    if ~isequal(length(size(input)),numDims)
        eid = 'Size:wrongDimensions';
        msg = ['Input must have dimensions: ',num2str(numDims)];
        throwAsCaller(MException(eid,msg))
    end
end

mustBeOfClass 函数通过要求与类名称匹配来实现严格的类匹配。更一般的方法是使用 isa 函数来同时匹配指定类的子类。

mustBeEqualSize 和 mustBeDims 函数对输入参数执行严格的声明。

fCustomValidators('character vector',144)

Invalid input argument at position 1. Input must be of class double

在此调用中，第一个输入的维数是错误的，因此验证函数返回自定义错误消息。

fCustomValidators(ones(2,2,4),144)

Invalid input argument at position 1. Input must have 2 dimensions

mustBeEqualSize 验证函数将第二个输入限制为特定维度，如错误消息所示。

fCustomValidators(ones(2,2),144)

Invalid input argument at position 2. Input must be of size [5  3]

要了解相关预定义验证函数的信息，请参阅 mustBeA、mustBeFloat 和 mustBeVector。

参数验证中的 nargin

nargin 函数针对当前正在执行的函数，返回函数调用中给定函数输入参数的数目。使用函数参数验证时，函数内 nargin 返回的值是调用函数时提供的位置参数的数量。

重复参数是位置参数，因此调用时传递给函数的重复参数的个数将计入 nargin 返回的值。

nargin 返回的值不包括未包含在函数调用中的可选参数。此外，nargin 不对任何名称-值参数进行计数。

使用 nargin 确定在调用时是否将可选位置参数传递给函数。例如，此函数声明三个位置参数和一个名称-值参数。函数通过以下方式确定在调用时传递哪些参数。

function result = fNargin(a,b,c,namedargs)
    arguments
        a (1,1) double
        b (1,1) double
        c (1,1) double = 1
        namedargs.Format (1,:) char
    end

    % Function code
    switch nargin
        case  2
            result = a + b;
        case 3
            result = a^c + b^c;
    end
    if isfield(namedargs,"Format")
        format(namedargs.Format);
    end
end

在此函数调用中，nargin 的值是 2：

result = fNargin(3,4)

result =

     7

在此函数调用中，nargin 的值是 3：

result = fNargin(3,4,7.62)

result =

   4.3021e+04

在此函数调用中，nargin 的值是 3：

result = fNargin(3,4,7.62,Format="bank")

result =

      43020.56

变量和函数访问的限制

arguments 代码块存在于函数的工作区中。使用 import 命令添加到函数作用域的任何包、类或函数都将添加到 arguments 代码块的作用域中。

对验证函数和默认值表达式可见的变量只有已声明的输入变量。在以下函数中，c 的默认值派生自 a 和 b。

function c = f(a,b,c)
    arguments
        a uint32
        b uint32
        c uint32 = a * b
    end
 
    % Function code
    ...
end

但是，您无法引用尚未在 arguments 代码块中声明的输入变量。例如，在上述函数中对参数 a 使用以下声明是无效的，因为 b 和 c 尚未声明。

arguments
    a uint32 = b * c
    b uint32
    c uint32
end

参数验证表达式只能引用此前声明过（因此经过验证）的参数。名称-值参数的验证函数和默认值无法访问其他名称-值参数。

调试参数块

在参数块内部调试时，工作区为只读。这意味着可以检查工作区并查看赋给变量的值。但是，当工作区为只读时，无法创建新变量或更改赋给现有变量的值。一旦调试器位于参数块之外，就可以再次创建或编辑变量。