Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

arguments

声明函数参数验证

语法

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

arguments (Repeating)
    ... 
end

说明

示例

arguments ... end 声明函数的输入参数。arguments 代码块是可选的。如果要包含 arguments 代码块,它必须出现在函数的第一个可执行代码行之前。函数可以包括多个 arguments 代码块。

每个参数可以有一个或多个约束或一个默认值,如以下语法所示:

argName (dimensions) dataType {validators} = defaultValue

  • (dimensions) - 输入大小,指定为包含两个或多个数值的以逗号分隔的列表,如 (1,2)(3,5,2)(1,:)。冒号表示该维度可以包含任意长度。(dimensions) 不能包含表达式。

    输入的维度必须与 (dimensions) 完全匹配,或与 (dimensions) 指定的大小兼容。例如,(1,:) 指定输入必须为 1×n 行向量,但 n×1 列向量是兼容的。该函数将行向量输入重构为列向量。同样,大小为 (2,3) 的值允许标量输入,但它将输入扩展为 2×3 矩阵。有关详细信息,请参阅 基本运算的兼容数组大小

  • dataType - 数据类型,指定为类名称,如 double。输入必须为指定的类型或可以转换为该类型的类型。例如,指定 double 的函数接受 single 类型的值并将它们转换为 double

  • {validators} - 以逗号分隔的验证函数(如 mustBeNumericmustBeScalarOrEmpty)列表,用花括号括起来。当输入参数与其条件不匹配时,验证函数会出错。与 dataType 不同,验证函数不修改输入参数。有关验证函数的列表,请参阅 参数验证函数

  • defaultValue - 默认值必须符合指定的大小、类型和验证规则。默认值也可以是表达式。指定默认值会使该参数成为可选参数。可选参数必须位于函数签名中和 arguments 代码块中的必需参数后。

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

y = myFunction(x,options)

在 arguments 代码块中,将名称-值参数的名称指定为字段:

arguments 
    x
    options.Name1
    options.Name2
end 

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

arguments (Repeating) ... end 声明重复参数。

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

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

有关重复参数的详细信息,请参阅重复参数

示例

全部折叠

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

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)
m =

     3


s =

    1.6330

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

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

     3


s =

    1.6330

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

a = ["1" "3" "5"];
[m,s] = twoStats(a)
Error using twoStats
Invalid argument at position 1. Value must be numeric.

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

声明以 options 作为结构体名称的 myRectangle 函数。optionsLineStyleLineWidth 的两个字段是函数的名称-值参数中的名称:

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 函数接受参数 xystyle 的重复参数组。将输入参数 xy 限制为由双精度值或可转换为双精度值的值组成的向量。将 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

局限性

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

详细信息

全部折叠

支持的数据类型

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

提示

  • 使用数据类型限制会导致输入参数的隐式转换。例如:

    function y = myFunction(inputArg1)
        arguments
            inputArg1 (1,1) double
        end
        ...
    对于此函数,如果将字符串 "123" 作为输入参数传递,则 MATLAB 会将字符串转换为 double 类型的数值 123

    验证函数不会以任何方式更改输入值,因此为了避免数据类型转换,请使用一个或多个验证函数而不是数据类型来限制输入。例如:

    • 要避免将字符串转换为数值,请使用 mustBeAmustBeFloatmustBeNumeric

    • 要避免将数值转换为字符串,请使用 mustBeTextmustBeTextScalarmustBeNonZeroLengthText

    • 要避免大小转换,请使用 mustBeVectormustBeScalarOrEmpty

版本历史记录

在 R2019b 中推出