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

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

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

Шаг 1. Определите свою функцию.

Создайте функцию в файле с именем printPhoto.m. The 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) вместе со значением входа.

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

Шаг 4. Установите свойства, чтобы настроить синтаксический анализ (необязательно).

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

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

p.KeepUnmatched = true;

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

Шаг 5. Проанализируйте входы.

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

parse(p,filename,varargin{:})

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

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

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

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

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

В пределах printPhoto function, отобразите значения для некоторых входных входов:

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. Вызовите свою функцию.

Parser Входа рассчитывает получить входы следующим образом:

  • Необходимые входы сначала, в том порядке, в котором они добавляются к схеме разбора с 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'

При использовании аргументов имя-значение перед R2021a передайте имена как строки или векторы символов, а также разделите имена и значения запятыми. Для примера:

printPhoto('myfile.jpg','height',10,'width',8)

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

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

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

См. также

|

Похожие темы

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