inputParser

函数的输入解析器

说明

使用 inputParser 对象，用户可以通过创建输入解析器模式来管理函数的输入。要检查输入项，您可以为必需参量、可选参量和名称-值对组参量定义验证函数。还可以通过设置属性来调整解析行为，例如如何处理大小写、结构体数组输入以及不在输入解析器模式中的输入。

定义输入解析器模式后，调用 parse 函数。有关输入的信息存储在 inputParser 中。

输入名称和值	存储位置
有匹配的输入解析器模式	Results 属性
没有传递给函数，因此赋予默认值	UsingDefaults 属性
无匹配的输入解析器模式	Unmatched 属性

创建对象

语法

p = inputParser

描述

p = inputParser 创建具有默认属性值的输入解析器对象。

属性

CaseSensitive — 大小写是否匹配的指示符

false (默认) | true

表明检查参量名称时是否匹配大小写的指示符，指定为 false 或 true（或者指定为 0 或 1）。默认情况下，参量名称的匹配不区分大小写。例如，'a' 与 'A' 匹配。要进行区分大小写的匹配，请将 CaseSensitive 设置为 true（或 1）。

此属性值存储为逻辑值。

FunctionName — 错误消息中的函数名称

空字符向量 ''。 (默认) | 字符向量 | 字符串标量

在错误消息中显示的函数的名称，指定为字符向量或字符串标量。默认情况下，FunctionName 是一个空字符向量 ('')。通常将 FunctionName 设置为要验证的函数的名称。这样，如果 parse 函数遇到无效的输入参量，就会使用该函数名称报告错误。

此属性值存储为字符向量。

数据类型: char | string

KeepUnmatched — 匹配指示符

false (默认) | true

匹配指示符，它决定当输入解析器模式中找不到某个输入时是否引发错误，指定为 false 或 true（或指定为 0 或 1）。默认情况下，如果输入参量名称与输入解析器模式中定义的参量名称不匹配，parse 函数将引发错误。要抑制错误并存储输入参量名称和值，请将 KeepUnmatched 设置为 true（或 1）。inputParser 将不匹配的输入参量名称和值存储在 Unmatched 属性中。

此属性值存储为逻辑值。

PartialMatching — 部分匹配指示符

true (默认) | false

部分匹配指示符，它决定是否接受部分匹配的输入名称作为有效输入，指定为 true 或 false（或指定为 1 或 0）。默认情况下，如果输入参数名称是输入解析器模式中定义的参数名称的前导子字符串，则视为是有效输入，而且输入值与该参数匹配。如果输入参数有多个可能的匹配项，MATLAB^® 将引发错误。要使输入参数名称与输入解析器模式中的名称按照 CaseSensitive 属性的设置精确匹配，请将 PartialMatching 设置为 false（或 0）。

只有使用 addParameter 函数添加到输入解析器模式中的参量支持部分匹配。

• 如果 StructExpand 属性的值为 true（或 1），则 inputParser 不支持与输入参数名称对应的结构体字段名称的部分匹配。

• 如果 PartialMatching 和 KeepUnmatched 都为 true（或 1），则 MATLAB 不会引发错误。在这种情况下，它会将具有多义性的参数名称存储在 Unmatched 属性中。

此属性值存储为逻辑值。

StructExpand — 结构体指示符

true (默认) | false

结构体指示符，它决定是将结构体解释为单个输入还是一组参数名称-值对组，指定为 true 或 false（或指定为 1 或 0）。默认情况下，inputParser 将结构体展开为一个个单独的输入，其中每个字段名称对应一个输入参数名称。要将结构体视为单个输入参量，请将 StructExpand 指定为 false（或 0）。

此属性值存储为逻辑值。

Parameters — 参量名称

字符向量元胞数组

此 属性 为只读。

输入解析器模式中定义的参量名称，以字符向量元胞数组的形式存储。每个向输入解析器方案中添加输入参量的函数都会更新 Parameters 属性。这些函数包括 addRequired、addOptional 和 addParameter。

数据类型: cell

Results — 结果

结构体

此 属性 为只读。

结果，指定为有效输入参量的名称和对应的值，以结构体的形式存储。有效输入参量是指名称与输入解析器模式中定义的参量匹配的输入参量。Results 结构体的每个字段对应于输入解析器模式中一个参量的名称。parse 函数会填充 Results 属性。

数据类型: struct

Unmatched — 不匹配输入

结构体

此 属性 为只读。

与输入解析器模式不匹配的输入的名称和值，以结构体的形式存储。如果 KeepUnmatched 属性设置为默认值 false（或 0），或者所有输入都与输入解析器模式匹配，则 Unmatched 是一个不包含任何字段的 1×1 结构体。否则，Unmatched 结构体的每个字段对应于一个与输入解析器模式中定义的参量不匹配的输入参量的名称。

parse 函数会填充 Unmatched 属性。

数据类型: struct

UsingDefaults — 未显式传递给函数的输入

字符向量元胞数组

此 属性 为只读。

未显式传递给函数的输入，以字符向量元胞数组的形式存储。这些输入参量将被赋予 Results 属性中的默认值。parse 函数会填充 UsingDefaults 属性。

数据类型: cell

对象函数

addOptional	将可选的位置参量添加到输入解析器模式中
addParameter	在输入解析器模式中添加可选的名称-值对组参量
addRequired	将必需的位置参量添加到输入解析器模式中
parse	解析函数输入
addParamValue	（不推荐）在输入解析器模式中添加可选的名称-值对组参量

您可以按任何顺序调用 addRequired、addOptional 和 addParameter 函数来定义输入解析器模式。但是，当您调用使用输入解析器的函数时，将按以下顺序传递参量：

1. 必需参量

2. 任何可选的位置参量

3. 任何名称-值对组

示例

输入验证

检查必需参量和可选参量的有效性。

在文件 findArea.m 中创建一个函数。findArea 函数要求必须指定 width 输入参量，并接受可变数目的附加输入。输入解析器模式指定以下参量条件：

• width（必需参量）。由于必需参量是位置参量，因此 width 必须是 findArea 函数的第一个参量。输入解析器检查 width 是否为正数值标量。

• height（可选参量）。由于可选参量是位置参量，因此如果 height 是 findArea 函数的参量，则它必须是第二个参量。输入解析器检查 height 是否为正数值标量。

• 'units' 及其关联值（名称-值对组）。名称-值对组是可选的。当您调用 findArea 函数时，可在位置参量后面以任何顺序指定名称-值对组。输入解析器检查 'units' 的值是否为字符串。

• 'shape' 及其关联值（另一个名称-值对组）。输入解析器检查 'shape' 的值是否包含在 expectedShapes 数组中。

function a = findArea(width,varargin)
   defaultHeight = 1;
   defaultUnits = 'inches';
   defaultShape = 'rectangle';
   expectedShapes = {'square','rectangle','parallelogram'};

   p = inputParser;
   validScalarPosNum = @(x) isnumeric(x) && isscalar(x) && (x > 0);
   addRequired(p,'width',validScalarPosNum);
   addOptional(p,'height',defaultHeight,validScalarPosNum);
   addParameter(p,'units',defaultUnits,@isstring);
   addParameter(p,'shape',defaultShape,...
                 @(x) any(validatestring(x,expectedShapes)));
   parse(p,width,varargin{:});
   
   a = p.Results.width*p.Results.height; 
end

多次调用 findArea 函数。输入解析器不会对以下任何函数调用引发错误。

a = findArea(7);
a = findArea(7,3);
a = findArea(13,'shape','square');
a = findArea(13,'units',"miles",'shape','square');

使用与输入解析器模式不匹配的参量调用该函数。为 width 输入指定一个非数字值：

a = findArea('text')

Error using findArea (line 14)
The value of 'width' is invalid. It must satisfy the function: @(x)isnumeric(x)&&isscalar(x)&&(x>0).

为 'shape' 指定一个不支持的值。

a = findArea(4,12,'shape','circle')

Error using findArea (line 14)
The value of 'shape' is invalid. Expected input to match one of these values:

'square', 'rectangle', 'parallelogram'

The input, 'circle', did not match any of the valid values.

额外的参数值输入

存储不在输入方案中的参数名称和值输入，而不提示出错。

default = 0;
value = 1;

p = inputParser;
p.KeepUnmatched = true;
addOptional(p,'expectedInputName',default)
parse(p,'extraInput',value);

查看不匹配的参数名称和值：

p.Unmatched

ans = struct with fields:
    extraInput: 1

区分大小写

检查函数输入时强制区分大小写。

p = inputParser;
p.CaseSensitive = true;
defaultValue = 0;
addParameter(p,'InputName',defaultValue)

parse(p,'inputname',10)

'inputname' is not a recognized parameter. For a list of valid name-value pair arguments, see the documentation for this function.

结构体数组输入

将结构体参量展开为名称-值对组。

s.input1 = 10;
s.input2 = 20;
default = 0;

p = inputParser;
addParameter(p,'input1',default)
addParameter(p,'input2',default)
parse(p,s)

p.Results

ans = struct with fields:
    input1: 10
    input2: 20

通过将 StructExpand 属性设置为 false，可将结构体视为单个参量。

s2.first = 1;
s2.random = rand(3,4,2);
s2.mytext = 'some text';

p = inputParser;
p.StructExpand = false;
addRequired(p,'structInput')
parse(p,s2)

results = p.Results

results = struct with fields:
    structInput: [1x1 struct]

fieldList = fieldnames(p.Results.structInput)

fieldList = 3x1 cell
    {'first' }
    {'random'}
    {'mytext'}

使用 validateattributes 解析输入项

创建一个可解析人员信息的函数，如果解析通过，则将该信息添加到元胞数组。

创建函数 addPerson，并包含使用 validateattributes 函数的输入解析器模式。addPerson 函数接受人员列表，根据需要修改该列表，然后返回该列表。使用持久性 inputParser 对象可避免在每次调用该函数时构建一个新对象。

function mlist = addPerson(mlist,varargin)
    persistent p
    if isempty(p)
        p = inputParser;
        p.FunctionName = 'addPerson';
        addRequired(p,'name',@(x)validateattributes(x,{'char'},...
            {'nonempty'}))
        addRequired(p,'id',@(x)validateattributes(x,{'numeric'},...
            {'nonempty','integer','positive'}))
        addOptional(p,'birthyear',9999,@(x)validateattributes(x,...
            {'numeric'},{'nonempty'}))
        addParameter(p,'nickname','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
        addParameter(p,'favColor','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
    end
    
    parse(p,varargin{:})
    
    if isempty(mlist)
        mlist = fieldnames(p.Results)';
    end
    mlist = [mlist; struct2cell(p.Results)'];
end

创建一个空列表并在表中添加一个人。

pList = {};
pList = addPerson(pList,78,'Joe');

Error using addPerson
The value of 'name' is invalid. Expected input to be one of these types:

char

Instead its type was double.

Error in addPerson (line 19)
parse(p,varargin{:})

解析失败，因为函数收到顺序不正确的参量，并试图将值 78 赋给 name。此条目没有添加到 pList 中。

将更多人员添加到列表中。

pList = addPerson(pList,'Joe',78);
pList = addPerson(pList,'Mary',3,1942,'favColor','red');
pList = addPerson(pList,'James',182,1970,'nickname','Jimmy')

pList =

  4×5 cell array

    'birthyear'    'favColor'    'id'     'name'     'nickname'
    [     9999]    '-'           [ 78]    'Joe'      '-'       
    [     1942]    'red'         [  3]    'Mary'     '-'       
    [     1970]    '-'           [182]    'James'    'Jimmy'   

提示

• 使用 addOptional 函数添加到输入解析器模式中的参量是位置参量。因此，将它们添加到输入解析器模式中的顺序应该与传递给函数时的顺序相同。

• 使用 addOptional 将单个参量添加到输入解析器模式。如果要解析可选的名称-值对组，请使用 addParameter 函数。

扩展功能

基于线程的环境

使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

此函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2007a 中推出

另请参阅

validateattributes | validatestring | varargin | arguments

主题

• 输入解析器验证函数
• 函数参量验证