031_Arguments_in_Matlab中的函数参数

在这里插入图片描述

函数参数

当我们定义函数时，我们可以使用如下的语法形式。当然Matlab中，并没有参数类型标识的语法，所以这里的x1,…,xM只是一个形式，实际上可以是任何类型的参数。

function [y1,...,yN] = myfun(x1,...,xM)

古早时期，我学Matlab的时候，通常会在函数中调用如下几个函数来进行处理，判断函数的类型、验证函数参数的有效性、实现函数的多态性。

nargin
nargout
varargin

在2019b版本之后，Matlab引入了新的函数参数处理语法arguments...end，这个方式更加直观，也更加方便。

function [y1,...,yN] = myfun(x1,...,xM)
    arguments
        x1 (1,1) double
        x2 (1,1) double
        ...
        xM (1,1) double
    end

    % 函数体
end

这个语法已经有四种形式，分别是：

输入参数
重复输入参数
输出参数
重复输出参数

输入参数

对于输入参数，我们可以使用如下的语法形式。

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

这里，argName是参数的名字，dimensions是参数的维度，class是参数的类型，validators是参数的验证函数，defaultValue是参数的默认值。

argName：形式参数的名字，可以是任意合法的变量名，必须出现在函数的定义中。
dimensions：形式参数的维度，至少要一个维度，(1,1)表示标量，(1,:)表示行向量，(:,1)表示列向量，(:,:)表示矩阵，只能是常量。
class：形式参数的类型，可以是任意合法的类型，如double、char、string、logical、cell、struct、table、function_handle等。
validators：形式参数的验证函数集合（元胞数组），函数名称，用于验证参数的有效性，这个函数会在参数不恰当时用throwAsCaller来抛出错误。
defaultValue：形式参数的默认值，如果没有提供参数，那么就会使用这个默认值，这样就能实现类似于Python中的默认参数的功能。

这里的几个要素，都是可选的，可以根据实际情况来选择是否使用。

function ret = abc(x1, x2, x3)
    arguments
        x1 (1,1) double  = - 1.0
        x2 (1,1) double = 0.0
        x3 (1,1) double = 1.0
    end
    ret = x1 + x2 + x3;
end

调用的方式可以是：

[abc(), abc(1), abc(1,2), abc(1,2,3)]

ans =

     0     2     4     6

当我们调用函数abc时，如果输入了不符合的参数，那么就会抛出错误。

验证函数

Matlab提供了一些内置的验证函数，可以用于验证参数的有效性，常见的，有如下几种。

数值特性
- 大于0，mustBePositive
- 大于等于0，mustBeNonnegative
- 小于0，mustBeNegative
- 小于等于0，mustBeNonpositive
- 整数，mustBeInteger
- 有限数，mustBeFinite
比较特性
- 大于某个值，mustBeGreaterThan
- 小于某个值，mustBeLessThan
数据类型
- 数值，mustBeNumeric
- 必须是某个类型，mustBeA
大小
- 非空，mustBeNonempty
- 行向量，mustBeRow
- 列向量，mustBeColumn
- 矩阵，mustBeMatrix
范围和成员
- 大小在某个范围内，mustBeInRange
- 是某个集合的成员，mustBeMember
文本
- 文件，mustBeFile
- 文件夹，mustBeFolder
类型
- 类型，mustBeType
- 类型或者空，mustBeTypeOrEmpty
- 有效变量名称，mustBeValidVariableName

如果内置的验证函数不能满足需求，我们也可以自定义验证函数，只需要满足如下的条件。

函数的输入参数是要验证的参数。
函数内部使用throwAsCaller来抛出错误。
或者调用error来抛出错误。

在使用自定义验证函数时，我们可以使用如下的语法形式。

function ret = nonsense(x1, x2, x3)
    arguments
        x1 {
    
    myValidator1}
        x2 {
    
    myValidator2(x2, 10)}
        x3 {
    
    myValidator3(x3, x1)}
    end
    ret = numel(x1) + numel(x2) + numel(x3);
end

function myValidator1(x)
    if ~isreal(x)
        throwAsCaller(MException('myValidator1:NotReal', 'The input must be real.'));
    end
end

function myValidator2(x, y)
    if numel(x) < y
        throwAsCaller(MException('myValidator2:SizeTooSmall', sprintf('The input  size must be greater than %d.', y)));
    end
end

function myValidator3(x, y)
    if numel(x) < numel(y)
        throwAsCaller(MException('myValidator3:X2SizeTooSmall', 'The input size x3 must not less than size x1.'));
    end
end

可以看到，这个函数有几个特点：当函数的参数就是形式参数时，可以忽略参数名称，直接写{myValidator1}；当函数的参数除形式参数外还有别的参数时，需要写成完整的函数调用形式，
{myValidator2(x2, 10)}，在调用中，可以使用已经定义的形式参数，也可以使用常量。

这个throwAsCaller函数，可以用于抛出错误，这个错误会在调用函数的地方抛出，而不是在验证函数的地方抛出，这样就能更好的定位错误。

nonsense(1,1:11,3)

ans =

    13

命名参数的使用

在arguments块中，用类似于结构体的方式来定义参数，这样就可以实现命名参数的功能。

function printScore(x, options)
    arguments
        x (1,1) double = 0
        options.Name (1,1) string = "Anonymous"
        options.Age (1,1) double = 18
    end

fprintf('name: %s, age: %d, score: %f\n', options.Name, options.Age, x);
end

这样，我们就可以使用如下的方式来调用函数。

printScore()
printScore(60)
printScore(60, Name="John Doe")
printScore(60, Age=12)
printScore(60, Name="John Doe", Age=12)

name: Anonymous, age: 18, score: 0.000000
name: Anonymous, age: 18, score: 60.000000
name: John Doe, age: 18, score: 60.000000
name: Anonymous, age: 12, score: 60.000000
name: John Doe, age: 12, score: 60.000000

输出参数

对于输出参数，我们可以使用如下的语法形式。除默认值之外，与输入参数的定义方式是一样的。

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

举个例子：

function [xfinal,yfinal] = rotatePatch(angle)
    arguments (Output)
        xfinal {
    
    mustBePositive}
        yfinal {
    
    mustBePositive}
    end
    xfinal = cos(angle);
    yfinal = sin(angle);
end

% 获得输出的个数
n = nargout(@printScore);
% 利用逗号分割列表赋值输出的方式调用函数
[xy{
    
    1:n}] = rotatePatch(0.1 * pi);
% 利用逗号分割列表来把输出转化为数组
[xy{
    
    :}]

ans =

    0.9511    0.3090

重复参数

重复输入参数

当我们需要类似于plot函数的重复参数时，可以使用如下的语法形式。

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

这是，我们就能采取如下的方式来调用函数。

func(arg1_1, ..., arg1_M, arg2_1, ..., arg2_M, arg3_1, ..., arg3_M)

而在函数的定义中，形式参数就会时一个元胞数组，这个元胞数组就会包含所有的重复参数。

argName1 = {
    
    arg1_1, ..., arg3_1}
argName2 = {
    
    arg1_2, ..., arg3_2}
...
argNameM = {
    
    arg1_M, ..., arg3_M}

例如，我们可以定义一个函数，用于绘制多条曲线：

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

x1 = 1:10;
y1 = 1:10;
s1 = “:”;
x2 = 1:7;
y2 = 1:1.5:10;
s2 = “–”;
fRepeat(x1,y1,s1,x2,y2,s2)

重复输出参数

同样，也可以设置重复输出参数：

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

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

总结

arguments块中，可以定义输入参数、输出参数、重复输入参数、重复输出参数。
可以使用内置的验证函数，也可以自定义验证函数。
可以使用结构体的方式来定义命名参数。
throwAsCaller可以用于抛出错误, error也可以用于抛出错误。