Анализ входных параметров функции

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

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

Шаг 1. Определение функции.

Создайте функцию в файле с именем printPhoto.m. Функция printPhoto имеет требуемый вход того для имени файла и дополнительные входные параметры для конца (глянцевый или матовый), цветовое пространство (RGB или CMYK), ширина и высота.

function printPhoto(filename,varargin)

В вашем операторе объявления функции задайте требуемые входные параметры сначала. Используйте varargin, чтобы поддержать дополнительные входные параметры.

Шаг 2. Создание объекта InputParser.

В вашей функции вызовите inputParser, чтобы создать объект синтаксического анализатора.

p = inputParser;

Шаг 3. Добавление входных параметров к схеме.

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

Для каждого входа можно задать указатель на функцию валидации, которая проверяет вход и возвращает логический скаляр (true или false) или ошибки. Функцией валидации может быть существующая функция MATLAB (такая как ischar или isnumeric) или функция, которую вы создаете (такие как анонимная функция или локальная функция).

В функции printPhoto filename является необходимым входом. Задайте finish и color как дополнительные входные параметры, и width и height как дополнительные пары значения параметров.

defaultFinish = 'glossy';
validFinishes = {'glossy','matte'};
checkFinish = @(x) any(validatestring(x,validFinishes));

defaultColor = 'RGB';
validColors = {'RGB','CMYK'};
checkColor = @(x) any(validatestring(x,validColors));

defaultWidth = 6;
defaultHeight = 4;

addRequired(p,'filename',@ischar);
addOptional(p,'finish',defaultFinish,checkFinish)
addOptional(p,'color',defaultColor,checkColor)
addParameter(p,'width',defaultWidth,@isnumeric)
addParameter(p,'height',defaultHeight,@isnumeric)

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

Входные параметры, добавленные с addParameter, не позиционны, таким образом, можно передать значения для height прежде или после значений для width. Однако входные параметры значения параметров требуют, чтобы вы передали входное имя ('height' или 'width') наряду со значением входа.

Если ваша функция принимает дополнительные входные строки или векторы символов и название параметра и пары значения, задайте функции валидации для дополнительных входных параметров. В противном случае Входной Синтаксический анализатор интерпретирует дополнительные строки или векторы символов как названия параметра. Например, функция валидации checkFinish гарантирует, что printPhoto интерпретирует 'glossy' как значение для finish и не как имя недопустимого параметра.

Шаг 4. Задание свойств для настройки парсинга (опционально).

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

Позвольте printPhoto принимать дополнительные входные параметры значения параметров, которые не совпадают с входной схемой путем установки свойства KeepUnmatched Входного Синтаксического анализатора.

p.KeepUnmatched = true;

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

Шаг 5. Парсинг входных параметров.

В вашей функции вызовите метод parse. Передайте значения всех входных параметров функции.

parse(p,filename,varargin{:})

Шаг 6. Использование входных параметров в функции.

Доступ к проанализированным входным параметрам с помощью этих свойств объекта inputParser:

  • Results — Массив структур с именами и значениями всех входных параметров в схеме.

  • Unmatched — Массив структур с названиями параметра и значениями, которые передаются функции, но не находятся в схеме (когда KeepUnmatched является true).

  • UsingDefaults Массив ячеек с именами дополнительных входных параметров, которые присвоены их значения по умолчанию, потому что они не передаются функции.

В функции printPhoto отобразите значения для некоторых входных параметров:

disp(['File name: ',p.Results.filename])
disp(['Finish: ', p.Results.finish])

if ~isempty(fieldnames(p.Unmatched))
   disp('Extra inputs:')
   disp(p.Unmatched)
end
if ~isempty(p.UsingDefaults)
   disp('Using defaults: ')
   disp(p.UsingDefaults)
end

Шаг 7. Вызывание вашей функции.

Входной Синтаксический анализатор ожидает получать входные параметры можно следующим образом:

  • Необходимые входные параметры сначала, в порядке они добавляются к схеме парсинга с addRequired.

  • Дополнительные позиционные входные параметры в порядке они добавляются к схеме с addOptional.

  • Позиционные входные параметры перед названием параметра и входными параметрами пары значения.

  • Названия параметра и значения в форме Name1,Value1,...,NameN,ValueN.

Передайте несколько комбинаций входных параметров к printPhoto, некоторые допустимые и некоторые недопустимые:

printPhoto('myfile.jpg')
File name: myfile.jpg
Finish: glossy
Using defaults: 
    'finish'    'color'    'width'    'height'
printPhoto(100)
Error using printPhoto (line 23)
The value of 'filename' is invalid. It must satisfy the function: ischar.
printPhoto('myfile.jpg','satin')
Error using printPhoto (line 23)
The value of 'finish' is invalid. Expected input to match one of these strings:

'glossy', 'matte'

The input, 'satin', did not match any of the valid strings. 
printPhoto('myfile.jpg','height',10,'width',8)
File name: myfile.jpg
Finish: glossy
Using defaults: 
    'finish'    'color'

Чтобы передать значение для n th позиционный вход, любой задает значения для предыдущего (n – 1) входные параметры или передает вход как пару значения и название параметра. Например, эти вызовы функции присваивают те же значения finish ('glossy' по умолчанию) и color:

printPhoto('myfile.gif','glossy','CMYK')  % positional

printPhoto('myfile.gif','color','CMYK')   % name and value

Смотрите также

|

Похожие темы

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