何时使用参量验证

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

arguments 代码块语法

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

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

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

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

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

验证大小和类

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

    % Function code
    ...
end

验证函数

验证函数是一个 MATLAB 函数，如果参量值不满足某些要求，该函数会引发错误。验证函数不返回值，并且与类和大小不同，验证函数无法更改它们正在验证的参量的值。

在验证过程中，MATLAB 将参量值传递给为该参量列出的每个验证函数。传递给验证函数的值是在设定类和大小时进行任意转换之后的结果。MATLAB 从左到右调用每个函数，并引发遇到的第一个错误。

有关预定义的验证函数的表，请参阅参量验证函数。

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.';
        error(eid,msg)
    end
end

默认值

输入参量默认值可以是满足大小、类和验证函数要求的任何常量或表达式。在参量声明中指定默认值会使参量变为可选。当参量不包含在函数调用中时，MATLAB 将使用默认值。默认值表达式在每次使用默认值时进行计算。

可选参量必须位于函数签名中和 arguments 代码块中的必需参量后。有关可选参量的详细信息，请参阅验证必需和可选位置参量。

转换为声明的类和大小

类验证和大小验证都可以更改参量的值。以下是 MATLAB 可以执行的一些转换示例。

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

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

因此，函数体中经过验证的值可能不同于调用函数时传递的值。有关类转换的详细信息，请参阅Implicit Class Conversion。为了避免验证过程中的类和大小转换，请改用参量验证函数。有关详细信息，请参阅Use Validation Functions to Avoid Unwanted Class and Size Conversions。

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

输出参量验证

从 R2022b 开始，可以对输出参量使用参量验证。与输入参量类似，您可以验证输出参量的类和大小，还可以应用验证函数。但是，您无法为输出参量指定默认值，也无法引用以前声明的参量。输出参量验证始终是可选的。添加输出参量验证有助于提高代码的可读性，并在可能随时间而变化的代码中使输出保持一致。

必须使用单独的 arguments 块来验证输入和输出参量。在 arguments 语句后定义参量块 (Input) 或 (Output) 的类型。如果同时使用 (Input) 和 (Output) 参量块，则 (Output) 块必须跟在 (Input) 块后。如果没有指定类型，则 MATLAB 假定该块包含输入参量。

有关详细信息，请参阅 arguments。

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

    arguments (Output)
        out (1,:) double
    end

    % Function code
    ...
end

参量的种类

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

参量验证的顺序

在调用函数时，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

变量和函数访问的限制

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

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

调试参量块

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