В этом примере показано, как задать обязательные и необязательные входы, назначить значения по умолчанию необязательным входам и проверить все входы пользовательской функции с помощью Input Parser.
Input Parser предоставляет последовательный способ проверки и назначения значений по умолчанию входам, улучшая робастность и поддерживаемость вашего кода. Чтобы подтвердить входы, можно использовать преимущества существующего MATLAB® функций или написать свои собственные стандартные программы валидации.
Создайте функцию в файле с именем printPhoto.m
. The printPhoto
функция имеет один необходимый вход для имени файла и необязательные входы для конца (глянцевый или матовый), цветового пространства (RGB или CMYK), ширины и высоты.
function printPhoto(filename,varargin)
В операторе объявления функции сначала задайте необходимые входы. Использование varargin
для поддержки необязательных входов.
В рамках своей функции вызывайте inputParser
для создания объекта синтаксического анализатора.
p = inputParser;
Добавьте входы в схему анализа в функции с помощью 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
а не как недопустимое имя параметра.
По умолчанию Input Parser делает предположения о чувствительности случая, именах функции, входах массива структур и том, разрешать ли дополнительные названия и значения параметра, которых нет в схеме. Свойства позволяют вам явным образом определять поведение. Установите свойства с помощью записи через точку, подобно присвоению значений массиву структур.
Разрешить printPhoto
принять дополнительные значения параметров входов, которые не соответствуют схеме входа путем установки KeepUnmatched
свойство Входного анализатора.
p.KeepUnmatched = true;
Если KeepUnmatched
является false
(по умолчанию), Input Parser выдает ошибку, когда входы не соответствуют схеме.
В рамках вашей функции вызовите parse
способ. Передайте значения всех входных параметров функции.
parse(p,filename,varargin{:})
Доступ к проанализированным входам с помощью этих свойств 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
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