arguments

声明函数参量验证

自 R2019b 起

语法

arguments
    argName1 (dimensions) class {validators} = defaultValue
    ...
    argNameN ...
end

arguments (Repeating)
    argName1 (dimensions) class {validators} = defaultValue
    ...
    argNameN ... 
end

arguments (Output)
    argName1 (dimensions) class {validators}
    ...
    argNameN ...
end

arguments (Output,Repeating)
    argName (dimensions) class {validators}
end

说明

输入参量块

示例

arguments ... end 声明函数的输入参量。参量块是可选的。如果包含一个或多个 arguments 块，它们必须出现在函数的第一个可执行代码行之前。MATLAB^® 将任何未显式标记为 Input 或 Output 的参量块视为输入块。

每个参量可以有一个或多个约束或一个默认值，如以下语法所示：

argName (dimensions) class {validators} = defaultValue

(dimensions) - 输入大小，指定为包含两个或多个数值的以逗号分隔的列表，如 (1,2)、(3,5,2) 或 (1,:)。冒号表示该维度可以包含任意长度。(dimensions) 不能包含表达式。
输入的维度必须与 (dimensions) 完全匹配，或与 (dimensions) 指定的大小兼容。例如，(1,:) 指定输入必须为 1×n 行向量，但 n×1 列向量是兼容的。该函数将行向量输入重构为列向量。同样，大小为 (2,3) 的值允许标量输入，但它将输入扩展为 2×3 矩阵。有关详细信息，请参阅基本运算的兼容数组大小。
class - 按名称指定的类或 MATLAB 数据类型，如 double。输入必须为指定的类型或可以转换为该类型的类型。例如，指定 double 的函数接受 single 类的值并将它们转换为 double。有关转换的详细信息，请参阅Implicit Class Conversion。
{validators} - 以逗号分隔的验证函数（如 mustBeNumeric 和 mustBeScalarOrEmpty）列表，用花括号括起来。当输入参量与其条件不匹配时，验证函数会出错。与 class 不同，验证函数不修改输入参量。有关验证函数的列表，请参阅参量验证函数。
defaultValue - 默认值必须符合指定的大小、类型和验证规则。默认值也可以是表达式。指定默认值会使该参量成为可选参量。可选参量必须位于函数签名中和 arguments 块中的必需参量后。

对于名称-值参量，arg 使用 nv.name 的形式，其中 nv 是函数签名中的结构体名称，name 是参量块中的参量名称。例如，使用名为 options 的结构体定义接受名称-值参量的函数。

y = myFunction(x,options)

在参量块中，将名称-值参量的名称指定为字段：

arguments 
    x
    options.Name1
    options.Name2
end

有关通常情况下使用 arguments 块的详细信息，请参阅 arguments 代码块语法。

示例

arguments (Repeating) ... end 声明重复输入参量。

例如，如果创建一个名为 myplot 且包含重复参量 X、Y 和 style 的函数，则该函数接受这三个参量的多个组，例如 myplot(x1,y1,style1,x2,y2,style2)。MATLAB 创建一个元胞数组，其中包含为该参量传入的所有值。

函数只能包含一个重复输入参量块。如果该函数同时包含重复参量和名称-值参量，请在重复参量块后在单独的参量块中声明名称-值参量。

有关对重复参量使用验证的详细信息，请参阅验证重复参量。

输出参量块

示例

arguments (Output) ... end 声明函数的输出参量。输出参量块是可选的。如果包含一个或多个输出 arguments 块，它们必须出现在所有输入块之后，函数的第一个可执行代码行之前。当在函数中同时包含输入和输出块时，为了提高可读性，建议显式包含 (Input) 和 (Output) 属性。请参阅使用参量验证重复输出中的示例。（从 R2022b 开始）

与输入参量一样，输出参量也可以有一个或多个约束，如以下语法所示：

argName (dimensions) class {validators}

有关其他详细信息，请参阅 arguments ... end 的描述。与输入参量不同，输出参量无法定义默认值，应用于输出参量的验证函数无法引用早期的输出参量。

示例

arguments (Output,Repeating) ... end 为函数声明重复输出参量。可以对重复输出参量使用参量验证，但每个函数只能定义一个重复输出参量。varargout 可以出现在重复输出参量块中，只要它是唯一的输出参量即可。（从 R2022b 开始）

示例

全部折叠

限制输入的大小和类型

编写一个函数，它将输入参量的大小限制为任意长度的行向量。使用验证函数将该向量的元素限制为数值。

function [m,s] = twoStats(x)
    arguments
        x (1,:) {mustBeNumeric}
    end
    m = mean(x,"all");
    s = std(x,1,"all");
end

对三元素行向量调用该函数。

a = [1 3 5];
[m,s] = twoStats(a)

带列向量调用该函数也有效，因为行向量和列向量是兼容的。

a = [1 3 5]';
[m,s] = twoStats(a)

如果带包含非数值的向量调用该函数，则 mustBeNumeric 验证函数会抛出错误。

a = ["1" "3" "5"];
[m,s] = twoStats(a)

Error using twoStats
Invalid argument at position 1. Value must be numeric.

定义名称-值参量

要为函数声明可选的名称-值参量，请在函数声明中包含结构体名称，并在 arguments 块中将参量名称定义为该结构体的字段。

声明以 options 作为结构体名称的 myRectangle 函数。options、LineStyle 和 LineWidth 的两个字段是函数的名称-值参量中的名称：

function myRectangle(X,Y,options)
    arguments
       X double
       Y 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)

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

定义重复输入参量

重复参量指可以在函数调用中重复零次或多次的单个参量或参量组。fRepeat 函数接受 x、y 和 style 的重复参量组。将输入参量 x 和 y 限制为由双精度值或可转换为双精度值的值组成的向量。将 style 限制为字符串 "--" 和 ":"。

function fRepeat(x,y,style)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
        style {mustBeMember(style,["--",":"])}       
    end
    
    % Reshape the cell arrays of inputs and call plot function
    z = reshape([x;y;style],1,[]);
    if ~isempty(z)
        plot(z{:});
    end
end

带两组输入调用 fRepeat。MATLAB 会创建一个元胞数组，其中包含为 x 传入的所有值，另一个数组包含为 y 传入的值，第三个数组包含为 style 传入的值。然后，该函数将这些数组重构为一个 1×6 元胞数组 z，并将其传递给 plot。

x1 = 1:10;
y1 = 1:10; 
s1 = ":"; 
x2 = 1:7;
y2 = 1:1.5:10;
s2 = "--";
fRepeat(x1,y1,s1,x2,y2,s2)

Plot showing two lines

通过参量验证限制输出值

编写一个函数，它将一个二维方形补片围绕点 (0.4, 0.4) 旋转用户指定的度数。返回最终图像的 x 和 y 坐标作为输出参量，并将这些值限制为正值。换句话说，仅当旋转的最终结果完全位于第一象限时，该函数才应返回坐标。

function [xfinal,yfinal] = rotatePatch(angle)
    arguments (Output)
        xfinal {mustBePositive}
        yfinal {mustBePositive}
    end
    x = [0.1 0.1 0.7 0.7];
    y = [0.1 0.7 0.7 0.1];
    p = patch(x,y,"red");
    rotate(p,[0 0 1],angle,[0.4 0.4 0])
    xfinal = p.Vertices(:,1);
    yfinal = p.Vertices(:,2);
end

用 15 度的角度调用该函数。此旋转不会将任何顶点移出第一象限，因此函数正常返回结果而不报错。

[x1,y1] = rotatePatch(15)

Plot of red square rotated counterclockwise 15 degrees

用 35 度的角度调用该函数，这会将左下顶点移出第一象限。负 x 坐标不满足输出参量验证，因此函数返回错误。

[x2,y2] = rotatePatch(35)

Invalid output 'xfinal'. Value must be positive.

Error in rotatePatch (line 12)
end

Plot of two red squares rotated counterclockwise 15 and 35 degrees

使用参量验证重复输出

编写一个函数，它接受重复的向量对组，并返回每对向量的总和。将输入和输出限制为行向量。

function vectorSum = repeatSum(a,b)
  arguments (Input,Repeating)
    a (1,:)
    b (1,:)
  end
  arguments (Output,Repeating)
    vectorSum (1,:)
  end

  n = numel(a);
  vectorSum{n} = a{n} + b{n};
  for i = 1:n-1
    vectorSum{i} = a{i} + b{i};
  end
end

在 for 循环为元胞数组预分配空间之前，计算最终输出并将其赋给 vectorSum{n}。在没有预分配空间的情况下在循环中扩展元胞数组有可能会对性能产生负面影响。

定义两个向量对组。将这两个对组作为输入调用 repeatSum。输入参量块验证将列向量转换为行向量，因为它们的大小兼容。

x1 = [1 2];
y1 = [3 4];
x2 = [1; 0];
y2 = [0; 1];
[sum1,sum2] = repeatSum(x1,y1,x2,y2)

由于输入限制为行向量，因此每个向量对组的总和始终为行向量。但是，输出验证有助于确保该函数始终生成行向量，即使该函数在以后进行了修改也是一样。例如，如果将输入验证更改为 mustBeVector 函数，则对组可以由一个行向量和一个列向量组成，无需转换。在这种情况下，x1 和 y2 的总和是一个矩阵。

x1 + y2

修改后的 repeatSum 的输出会出错，因为矩阵不会通过输出验证。

局限性

嵌套函数、抽象方法或句柄类析构函数方法不支持参量块。

详细信息

全部折叠

支持的数据类型

参量声明可以指定任何 MATLAB 类或 MATLAB 支持的外部定义的类，但不包括 Java 类、COM 类和在 MATLAB 软件版本 7.6 之前定义的 MATLAB 类（即不使用 classdef 关键字的类定义）。

提示

使用数据类型限制会导致输入参量的隐式转换。例如：
```
function y = myFunction(inputArg1)
    arguments
        inputArg1 (1,1) double
    end
    ...
```
对于此函数，如果将字符串 "123" 作为输入参量传递，则 MATLAB 会将字符串转换为 double 类型的数值 123。
验证函数不会以任何方式更改输入值，因此为了避免数据类型转换，请使用一个或多个验证器函数而不是数据类型来限制输入。例如：
- 要避免将字符串转换为数值，请使用 mustBeA、mustBeFloat 或 mustBeNumeric。
- 要避免将数值转换为字符串，请使用 mustBeText、mustBeTextScalar 或 mustBeNonZeroLengthText。
- 要避免大小转换，请使用 mustBeVector 或 mustBeScalarOrEmpty。
MATLAB 能够根据参量块中包含的信息为具有 arguments 块的函数提供代码自动填充和建议。无需 functionSignatures.json 文件即可获得此信息。有关自定义代码建议和自动填充的详细信息，请参阅自定义代码建议和自动填充。