验证名称-值参量
名称-值参量将名称与传递给函数的值相关联。名称-值参量:
可以按任何顺序传递给函数
始终为可选
必须在所有位置参量和重复参量之后声明
不能出现在使用
Repeating
属性的arguments
代码块中必须使用唯一名称,即便使用多个名称-值结构体时也是如此
不能与位置参量同名
使用圆点表示法在 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
会导致错误。一般情况下,推荐使用全名,以提高代码可读性和避免意外行为。
相同的名称-值参量可以在一个函数调用中重复而不会报错,但最后一个指定的版本是 MATLAB 使用的版本。例如,以下对 plot
的调用指定了 Color
的值两次。MATLAB 以红色显示图。
plot(x,y,Color="blue",LineStyle="--",Color="red")
名称-值参量的默认值
您可以为每个名称指定一个默认值。如果没有指定默认值,并且调用函数时不带该名称-值参量,则该字段不存在于名称-值结构体中。如果没有向函数传递名称-值参量,MATLAB 仍会创建结构体,但它没有字段。
要确定在函数调用中传递了哪些名称-值参量,请使用 isfield
函数。
例如,以下函数定义两个必需位置参量(width
和 height
)和两个名称-值参量(LineStyle
和 LineWidth
)。在此示例中,options
结构体有两个字段(LineStyle
和 LineWidth
),其中包含默认值或在调用函数时指定为名称-值参量的值。
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)
在 R2021a 之前,将名称作为字符串或字符向量传递,并以逗号分隔名称和值。例如:
myRectangle(4,5,"LineStyle",":","LineWidth",2) myRectangle(4,5,"LineWidth",2,"LineStyle",":")
同时使用重复参量和名称-值参量
如果函数定义了重复参量,则您必须在重复参量代码块之后另加一个 arguments
代码块来声明名称-值参量。例如,此函数接受两个重复参量 x
和 y
。在指定 x
和 y
的所有重复项后,您可以指定一个名称-值参量,它将值 lin
或 log
赋给 PlotType
名称。
要确定函数调用是否包含 PlotType
参量,请使用 isfield
函数检查 scale
结构体中是否存在 PlotType
字段。
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")
在 R2021a 之前,将名称作为字符串或字符向量传递,并以逗号分隔名称和值。例如:
myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")
多个名称-值结构体
函数参量代码块可以包含多个名称-值结构体。但是,字段名称在所有结构体中必须唯一。此函数有两个名称-值结构体:lineOptions
和 fillOptions
。这些结构体不能有相同的字段名称。
myRectangle
函数中的参量是:
width
和height
是double
类型的必需位置参量。lineOptions.LineStyle
是标量字符串,默认值为"-"
。lineOptions.LineWidth
是标量数值,默认值为1
。fillOptions.Color
是字符串。fillOptions.Pattern
对其值没有任何限制。
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
语法实现稳健的参量解析。
强制应用有效名称
在参量块中定义名称-值参量可确保名称是有效的标识符。这还有助于确保您的参量同时适用 "name",value
和 name=value
语法。例如,使用无效标识符的名称-值参量用在逗号分隔语法中是没问题的:
myFunction(data,"allow-empty",true)
allow-empty=true
语法执行同一调用则会引发错误。在参量块中定义名称-值参量可确保您定义的名称是有效的 MATLAB 变量名称,并且符合 name=value
语法。避免因文本输入而导致的意外结果
同时包含可选文本输入和名称-值参量的函数存在 MATLAB 误将文本输入解释为名称-值参量名称的风险。以下函数包括两个可选的文本输入和一个名称-值参量。
function mySignal(tag,unit,opts) arguments tag = "0" unit = "ampere" opts.Magnifier {mustBeMember(opts.Magnifier,["small","medium","big"])} end end
tag
的值设置为 "Mag"
并将 unit
的值设置为 "coulomb"
:mySignal("Mag","coulomb")
"Mag"
解析为名称-值参量 Magnifer
。"coulomb"
不是该名称的有效值,因此函数出错。避免这种情况的一种方法是通过删除 tag
的默认值,使其成为必需的参量:
function mySignal(tag,unit,opts) arguments tag unit = "ampere" opts.Magnifier {mustBeMember(opts.Magnifier,["small","medium","big"])} end end
tag
设置为 "Mag"
,并且不会出错。另一种方法是将所有三个输入都作为名称-值参量。这有助于避免用户在指定输入时出错,因为每个值都与一个名称相关联,并且用户指定输入的顺序不会影响最终结果。
基于类属性的名称-值参量
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,...}
特定名称-值参量验证将覆盖类为单独指定的属性名称定义的验证。
例如,以下函数将名称-值参量定义为 matlab.graphics.chart.primitive.Bar
类的属性。该函数还覆盖属性名称 FaceColor
以仅允许这些特定值:red
或 blue
。
matlab.graphics.chart.primitive.Bar
类的 FaceColor
的默认值不是允许值(red
或 blue
)。因此,覆盖声明必须赋予一个默认值,该默认值满足 mustBeMember
验证函数施加的限制。也就是说,默认值必须为 red
或 blue
。
此函数使用 namedargs2cell
函数将名称-值结构体转换为名称与值相互交错的元胞数组。
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
和 y
调用函数。您还可以视需要传递 bar 函数支持的任何名称-值对组以及 FaceColor
的值,该值可以是 red
或 blue
。FaceColor
不允许使用其他值。
x = [1,2,3;4,5,6]; y = x.^2; myBar(x,y) myBar(x,y,FaceColor="red",BarLayout="grouped")