inputParser

Входной анализатор для функций

развернуть все на странице

Описание

The inputParser позволяет вам управлять входами в функцию путем создания схемы входного анализатора. Чтобы проверить вход, можно задать функции валидации для необходимых аргументов, необязательных аргументов и аргументов пары "имя-значение". Опционально можно задать свойства, чтобы настроить поведение анализа, такие как чувствительность случая обработки, входы массива структур и входы, которые не находятся во входной схеме анализатора.

После определения схемы входного анализатора вызовите parse функция. The inputParser хранит информацию о входах.

Входные имена и значенияГде хранится
Соответствие входной схемы синтаксического анализатораResults свойство
Не передан в функцию и, следовательно, присвоены значения по умолчаниюUsingDefaults свойство
Нет совпадающего входа синтаксической схемыUnmatched свойство

Создание

Синтаксис

p = inputParser

Описание

пример

p = inputParser создает объект входа parser со значениями свойств по умолчанию.

Свойства

расширить все

Индикатор, соответствующий случаю при проверке имен аргумента, заданный как false или true (или 0 или 1). По умолчанию имена аргумента не учитываются в регистре. Для примера, 'a' соответствует 'A'. Для учитывающих регистр соответствий установите CaseSensitive на true (или 1).

Это значение свойства сохранено как логическое значение.

Имя функции, отображаемой в сообщения об ошибке, задается как вектор символов или строковый скаляр. По умолчанию FunctionName - пустой символьный вектор (''). Как правило, вы задаете FunctionName на имя функции. Затем, если parse функция встречается с недопустимыми входными параметрами, она сообщает об ошибке с помощью имени функции.

Это значение свойства сохранено как вектор символов.

Типы данных: char | string

Соответствующий индикатор для выдачи ошибки, когда вход не найден в схеме входного анализатора, заданной как false или true (или 0 или 1). По умолчанию, parse функция выдает ошибку, если имя входного параметра не совпадает с именем, заданным в схеме входного анализатора. Чтобы подавить ошибку и сохранить имя и значение входного параметра, установите KeepUnmatched на true (или 1). The inputParser сохраняет несопоставленные имена и значения входных параметров в Unmatched свойство.

Это значение свойства сохранено как логическое значение.

Индикатор частичного соответствия для принятия частично совпадающих входных имен как допустимых, заданный как true или false (или 1 или 0). По умолчанию имена входных параметров, которые являются ведущими подстроками имен параметров в схеме входного анализатора, действительны, и входное значение совпадает с этим параметром. Если существует несколько возможных соответствий параметру входа, MATLAB® выдает ошибку. Чтобы потребовать, чтобы имена входных параметров совпадали с именем в схеме входного анализатора в точности, с учетом CaseSensitive свойство, задание PartialMatching на false (или 0).

Частичное соответствие поддерживается только аргументами, которые вы добавляете к схеме входного анализатора с помощью addParameter функция.

  • Если значение StructExpand свойство true (или 1), затем inputParser не поддерживает частичное соответствие для имен структурных полей, которые соответствуют именам входных параметров.

  • Если PartialMatching и KeepUnmatched являются ли оба true (или 1), MATLAB не выдает ошибку. Вместо этого он сохраняет неоднозначное имя параметра в Unmatched свойство.

Это значение свойства сохранено как логическое значение.

Структурный индикатор, который интерпретирует структуру как один вход или как набор пар "имя-значение" параметра, заданный как true или false (или 1 или 0). По умолчанию в inputParser расширяет структуры на отдельные входы, где каждое имя поля соответствует наименованию входного параметра. Чтобы рассматривать структуры как один входной параметр, задайте StructExpand как false (или 0).

Это значение свойства сохранено как логическое значение.

Это свойство доступно только для чтения.

Имена аргумента, заданные в схеме входного анализатора, хранятся в виде массива ячеек из векторов символов. Каждая функция, которая добавляет входного параметра в схему, обновляет Parameters свойство. Эти функции включают addRequired, addOptional, и addParameter.

Типы данных: cell

Это свойство доступно только для чтения.

Результаты, заданные как имена допустимых входных параметров и соответствующие значения, сохраненные как структура. Допустимый входной параметр является аргументом с именем, которое совпадает с аргументом, заданным в схеме входного анализатора. Каждое поле Results структура соответствует имени аргумента в схеме входного анализатора. parse функция заполняет Results свойство.

Типы данных: struct

Это свойство доступно только для чтения.

Несопоставленные входу имена и значения входов, которые не совпадают вход схемой синтаксического анализатора, хранятся как структура. Если на KeepUnmatched для свойства задано значение false (или 0), который является значением по умолчанию, или если все входы соответствуют схеме входного анализатора, то Unmatched - структура 1 на 1 без полей. В противном случае каждое поле Unmatched структура соответствует имени входного параметра, который не совпадает с аргументами, заданными в схеме входного анализатора.

parse функция заполняет Unmatched свойство.

Типы данных: struct

Это свойство доступно только для чтения.

Входы, не переданные явным образом в функцию, хранятся как массив ячеек из векторов символов. Этим входным параметрам присвоены значения по умолчанию в Results свойство. parse функция заполняет UsingDefaults свойство.

Типы данных: cell

Функции объекта

addOptionalДобавьте необязательный позиционный аргумент во входную схему синтаксического анализатора
addParameterДобавьте необязательный аргумент пары "имя-значение" во входную схему синтаксического анализатора
addRequiredДобавьте необходимый позиционный аргумент во входную схему синтаксического анализатора
parseСинтаксический анализ входных параметров функции
addParamValue(Не рекомендуемый) Добавить необязательный аргумент пары "имя-значение" во входную схему анализатора

Можно задать схему входного анализатора, вызвав addRequired, addOptional, и addParameter функционирует в любом порядке. Однако, когда вы вызываете функцию, которая использует входной анализатор, аргументы передаются в таком порядке:

  1. Необходимые аргументы

  2. Любые необязательные позиционные аргументы

  3. Любые пары "имя-значение"

Примеры

свернуть все

Проверьте валидность требуемых и необязательных аргументов.

Создайте функцию в файле findArea.m. The findArea функция требует width входной аргумент и принимает переменное количество дополнительных входов. Вход анализатора задаёт следующие условия аргумента:

  • width (необходимый аргумент). Поскольку требуемые аргументы являются позиционными, width должен быть первым аргументом в findArea функция. Входной анализатор проверяет, что width положительный, скалярный и числовой.

  • height (необязательный аргумент). Поскольку необязательные аргументы являются позиционными, если height является аргументом в findArea функция, тогда это должен быть второй аргумент. Входной анализатор проверяет, что height положительный, скалярный и числовой.

  • 'units' и связанное с ним значение ( пара "имя-значение"). Пары "имя-значение" являются необязательными. Когда вы вызываете findArea function, задайте пары "имя-значение" в любом порядке после позиционных аргументов. Анализатор входа проверяет, чтобы значение для '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.
Открыть Live Script

Сохраните имя параметра и входов значения, которые не находятся в схеме входа, вместо выдачи ошибки. 

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.
Открыть Live Script

Разверните аргумент структуры в парах "имя-значение". 

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'}

Создайте функцию, которая анализирует информацию о людях и, если синтаксический анализ проходит, добавляет информацию к массиву ячеек.

Создайте addPerson функции и включите схему входа parser, которая использует validateattributes функция. The 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{:})

Синтаксический анализ не выполняется, поскольку функция получает аргументы в неправильном порядке и пытается назначить name значение 78. Эта запись не добавляется в 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'

Совет

  • Аргументы, добавленные к схеме входа parser с addOptional функция позиционна. Поэтому добавьте их к схеме входного анализатора в том же порядке, в котором они передаются в функцию.

  • Использовать addOptional для добавления отдельного аргумента во входную схему синтаксического анализатора. Если вы хотите проанализировать опциональную пару "имя-значение", используйте addParameter функция.

См. также

| | |

Темы

Введенный в R2007a

Документация MATLAB

Поддержка

Для просмотра документации необходимо авторизоваться на сайте