Валидация аргумента функции является способом объявить определенные ограничения на входные аргументы функции. Используя валидацию аргумента можно ограничить класс, размер и другие аспекты значений входного параметра функции без написания кода в теле функции выполнять эти тесты.
Валидация аргумента функции декларативна, который позволяет инструментам рабочего стола MATLAB® извлечь информацию о функции контролем определенных блоков кода. Путем объявления требований для входных параметров можно устранить громоздкий код проверки аргументов и улучшить удобочитаемость, робастность и поддерживаемость кода.
Синтаксис валидации аргумента функции упрощает процесс определения дополнительного, повторение и аргументы значения имени. Синтаксис также позволяет вам задать значения по умолчанию сопоставимым способом.
Использование валидации аргумента функции является дополнительным в функциональных определениях. Валидация аргумента является самой полезной в функциях, которые могут быть вызваны любым кодом и где валидность входных параметров должна быть определена прежде, чем выполнить функциональный код. Функции, которые спроектированы для использования другими, могут извлечь выгоду из соответствующего уровня ограничения на входные параметры аргумента и возможность возвратить определенные сообщения об ошибке на основе входных параметров к функциям.
В локальных и закрытых функциях, и в закрытых или защищенных методах, вызывающая сторона знает о входных требованиях, таким образом, эти типы функций могут быть вызваны допустимыми аргументами.
Вы не можете использовать синтаксис валидации аргумента во вложенных функциях, абстрактных методах или методах деструктора класса Handle. Для получения дополнительной информации о валидации аргумента в методах смотрите Валидацию Аргумента в Методах класса.
arguments
Блокируйте синтаксисВалидация аргумента define функций в блоках кода, которые разграничены ключевыми словами arguments
и end
. Если используется, arguments
блок должен запуститься перед первой исполняемой линией функции.
Можно использовать несколько arguments
блоки в функции, но все блоки должны произойти перед любым кодом, который не является частью arguments
блок.
Подсвеченная область в следующем коде показывает синтаксис для валидации аргумента.
Объявление аргумента функции может включать любой из этих видов ограничений:
Размер — длина каждой размерности, заключенной в круглые скобки
Класс — имя одного класса MATLAB
Функции — список, разделенный запятыми функций валидации, заключенных в фигурные скобки
Можно также задать значение по умолчанию для входного параметра в функциональном объявлении валидации для того аргумента. Значение по умолчанию должно удовлетворить заявленным ограничениям для того аргумента.
Размер валидации является размерностями входного параметра, заданного с неотрицательными целыми числами или двоеточиями (:
). Двоеточие указывает, что любая длина позволена в той размерности. Вы не можете использовать выражения для размерностей. Значение, присвоенное аргументу в вызове функции, должно быть совместимо с заданным размером, или MATLAB выдает ошибку.
Индексированные правила присвоения MATLAB применяются к техническим требованиям размера. Например, значение 1 на 1 совместимо с размером, заданным как (5,3)
потому что MATLAB применяет скалярное расширение. Кроме того, преобразование столбца строки MATLAB применяется так, чтобы размер задал как (1,:)
может принять размер 1 на n и n-1.
Вот некоторые примеры:
(1,1) — Вход должен быть точно 1 на 1.
(3,:) — Первая размерность должна быть 3, и второе измерение может быть любым значением.
Если вы не задаете размер, то любой размер позволен, если не ограничено функциями валидации.
Класс валидации является именем единого класса. Значение, присвоенное входному параметру функции, должно иметь заданный класс или конвертируемо к заданному классу. Используйте любой класс MATLAB или внешне заданный класс, который поддерживается MATLAB, кроме Java, COM-классов и определений классов MATLAB, которые не используют classdef
ключевое слово (классы, заданные перед Версией 7.6 программного обеспечения MATLAB).
Вот некоторые примеры:
char
— Введите должен иметь класс char
, или значение, которое MATLAB может преобразовать в char
, такой как string
.
double
— Введите может быть числовое значение любой точности.
cell
— Введите должен быть массив ячеек.
Пользовательский класс, такой как класс перечисления, может ограничить входные параметры более определенными значениями и позволяет вам управлять тем, какие преобразования поддерживаются.
Если вы не задаете класс, то любой класс позволен, если не ограничено функциями валидации.
Функцией валидации является функция MATLAB, которая выдает ошибку, если определенным требованиям не удовлетворяет значение аргумента. Функции валидации не делают возвращаемых значений и, в отличие от класса и размера, не может изменить значение аргументов, которые они подтверждают.
Во время процесса валидации MATLAB передает значение аргумента каждой функции валидации, перечисленной для того аргумента. Значение, переданное функциям валидации, является результатом любого преобразования, сделанного техническими требованиями размера и классом. MATLAB вызывает каждую функцию слева направо и выдает первую ошибку, с которой сталкиваются.
Для таблицы предопределенных функций валидации смотрите Функции Валидации Аргумента.
Значением по умолчанию аргумента может быть любая константа или выражение, которое удовлетворяет размеру, классу и требованиям функции валидации. Определение значения по умолчанию в объявлении аргумента приводит дополнительный аргумент. MATLAB использует значение по умолчанию, когда аргумент не включен в вызов функции. Выражения значения по умолчанию выполнены каждый раз, когда значение по умолчанию используется.
Примечание
Поскольку MATLAB подтверждает значение по умолчанию только, когда функция вызвана без значения для аргумента, недопустимое значение по умолчанию вызывает ошибку только, когда функция вызвана без того аргумента.
Дополнительные аргументы должны быть расположены после обязательных аргументов в функциональной подписи и в arguments
блок. Для получения дополнительной информации о дополнительных аргументах смотрите Необходимые и Дополнительные Позиционные параметры.
Аргументы подтверждены сверху донизу в arguments
блок. MATLAB подтверждает каждую часть объявления аргумента в определенном порядке. Сначала класс подтвержден, затем размер. Результат класса и валидаций размера передается функциям валидации. Каждый шаг является дополнительным в зависимости от того, являются ли класс, размер и функции валидации в объявлении аргумента.
Для получения дополнительной информации смотрите Порядок Валидации Аргумента.
И валидация класса и валидация размера могут изменить значение входного параметра из-за стандартных правил преобразования MATLAB. Поэтому подтвержденное значение в теле функции может отличаться от значения, переданного при вызывании функции. Правила преобразования выведены из правил, что MATLAB запрашивает индексируемое присвоение формы:
A(indices) = value
MATLAB может решить, что значение левой стороны имеет требования для класса и размера и, в определенных случаях, может преобразовать значение правой стороны, чтобы быть необходимого класса и размера.
Для сопутствующей информации смотрите Преобразования Класса и Размера Предотвращения.
Этот arguments
блок задает размер и класс трех входных параметров.
function out = myFunction(A, B, C) arguments A (1,1) string B (1,:) double C (2,2) cell end % Function code ... end
В этой функции переменные должны удовлетворить эти требования валидации:
A
строковый скаляр.
B
1-any вектор длины из, удваивается.
C
массив ячеек 2 на 2.
Следующая функция иллюстрирует, как входные параметры могут быть преобразованы, чтобы совпадать с классами, заданными в arguments
блок. SpeedEnum
класс является классом перечисления, созданным, чтобы задать значения, допускал третий входной параметр.
function forwardSpeed(a,b,c) arguments a double b char c SpeedEnum end % Function code disp(class(a)) disp(class(b)) disp(class(c)) end
Вот класс перечисления.
classdef SpeedEnum < int32 enumeration Full (100) Half (50) Stop (0) end end
Этот вызов функции использует входные значения, которые MATLAB может преобразовать в заявленные типы. Фактические типы аргумента в функции отображены, как выведено.
forwardSpeed(int8(4),"A string",'full')
double char SpeedEnum
Функции валидации могут ограничить входные параметры в более особенных методах. Можно использовать предопределенные функции валидации для многих общих видов валидации, и можно задать собственную функцию валидации, чтобы удовлетворить конкретным требованиям.
Например, эта функция задает следующее использование валидаций mustBeNumeric
, mustBeReal
, mustBeMember
, и локальная функция mustBeEqualSize
.
Введите x
должен быть действительный, числовой вектор-строка из любой длины.
Введите v
должен быть действительный, числовой вектор-строка тот же размер как x
.
Введите method
должен быть вектор символов, который является одним из трех позволенных вариантов. Поскольку method
задает значение по умолчанию, этот аргумент является дополнительным.
function myInterp(x,v,method) arguments x (1,:) {mustBeNumeric,mustBeReal} v (1,:) {mustBeNumeric,mustBeReal,mustBeEqualSize(v,x)} method (1,:) char {mustBeMember(method,{'linear','cubic','spline'})} = 'linear' end % Function code .... end % Custom validation function function mustBeEqualSize(a,b) % Test for equal size if ~isequal(size(a),size(b)) eid = 'Size:notEqual'; msg = 'Size of first input must equal size of second input.'; throwAsCaller(MException(eid,msg)) end end
Избегайте использования валидации аргумента функции в пользовательских функциях валидации. Для получения дополнительной информации об определении функций валидации и списка предопределенных функций валидации, смотрите Функции Валидации Аргумента.
Валидация аргумента функции может объявить четыре вида аргументов. Функции могут задать любой из этих видов аргументов, но аргументы должны быть заданы в следующем порядке:
Необходимые позиционные параметры
Дополнительные позиционные параметры
Повторение позиционных параметров
Дополнительные аргументы значения имени
Позиционные параметры должны быть переданы функции в определенном порядке. Положение значения, переданного в списке аргументов, должно соответствовать порядку, которым аргумент объявляется в arguments
блок. Все имена аргумента в arguments
блок должен быть уникальным.
Позиционные параметры в arguments
блок требуется при вызывании функции, если аргумент не задает значение по умолчанию. Определение значения по умолчанию в объявлении аргумента приводит позиционный аргумент, дополнительный, потому что MATLAB может использовать значение по умолчанию, когда никакое значение не передается в вызове функции.
Значением по умолчанию может быть константа или выражение, которое приводит к результату, который удовлетворяет объявлению аргумента. Выражение может относиться к аргументам, которые объявляются перед ним в arguments
блокируйтесь, но не аргументы, которые объявляются после него.
MATLAB выполняет выражение значения по умолчанию только, когда аргумент не включен в вызов функции.
Все дополнительные аргументы должны быть расположены после всех обязательных аргументов в arguments
блок. Например, в этом блоке аргумента, maxval
и minval
имейте значения по умолчанию, и являются поэтому дополнительными.
function myFunction(x,y,maxval,minval) arguments x (1,:) double y (1,:) double maxval (1,1) double = max(max(x),max(y)) minval (1,1) double = min(min(x),min(y)) end % Function code .... end
Можно вызвать эту функцию с любым из этих синтаксисов:
myFunction(x,y,maxval,minval) myFunction(x,y,maxval) myFunction(x,y)
Дополнительный позиционный параметр становится необходимым, когда его положение должно быть заполнено в вызове функции идентифицировать аргументы, которые прибывают после него. Таким образом, если вы хотите задать значение для minval
, необходимо задать значение для maxval
.
MATLAB позволяет вам проигнорировать входные параметры путем передачи символа тильды (~
) вместо аргумента. Можно задать функцию, которая игнорирует неиспользованные позиционные параметры путем добавления символа тильды (~
) в блоке аргументов, соответствующем положению аргумента в функциональной подписи. Добавьте символ тильды (~
) для каждого проигнорированного аргумента в функциональной подписи.
Проигнорированные аргументы не могут иметь значений по умолчанию или задать класс, размер или функции валидации.
Символ тильды (~
) обработан как дополнительный входной параметр, если он не сопровождается необходимым позиционным параметром. Например, в этой функции символ тильды (~
) представляет дополнительный аргумент.
function c = f(~) arguments ~ end % Function code end
Можно вызвать эту функцию без аргументов.
c = f
Или можно вызвать эту функцию с одним аргументом.
c = f(2)
В следующей функции, символ тильды (~
) представляет обязательный аргумент.
function c = f(~,x) arguments ~ x end % Function code ... end
Вызовы этой функции должны включать оба аргумента.
c = f(2,3)
Для получения дополнительной информации о вызывании функций с проигнорированными входными параметрами см. Игнорирование входных параметров функции.
Повторяющиеся аргументы являются позиционными параметрами, которые могут неоднократно задаваться как входные параметры. Объявите повторяющиеся аргументы в arguments
блокируйтесь, который включает Repeating
атрибут.
arguments (Repeating) arg1 arg2 ... end
Функции могут иметь только один Repeating
arguments
блокируйтесь, который может содержать один или несколько повторяющихся аргументов.
Функция, которая задает Repeating
arguments
блок может быть вызван нулем или большим количеством случаев всех аргументов в блоке. Если вызов функции включает повторяющиеся аргументы, то все аргументы в Repeating
arguments
блок должен быть включен для каждого повторения.
Например, если Repeating
arguments
блок задает аргументы x
и y
, затем каждое повторение должно содержать оба x
и y
.
Повторение аргументов не может задать значения по умолчанию и поэтому не может быть дополнительным. Однако можно вызвать функцию без включения любых аргументов повторения.
Функции должны объявить повторяющиеся аргументы после позиционных параметров и перед аргументами значения имени. Вы не можете задать аргументы значения имени в Repeating
блок. Для получения информации об аргументах значения имени смотрите Аргументы Значения Имени.
В функции каждый аргумент повторения становится массивом ячеек с числом элементов, равным количеству повторений, переданных в вызове функции. Валидация применяется к каждому элементу массива ячеек. Если функция вызвана с нулевыми случаями этого аргумента, массив ячеек имеет размер 1 на 0. Таким образом, это пусто.
Например, эта функция объявляет блок трех повторяющихся аргументов, x
Y
, и option
.
function [xCell,yCell,optionCell] = fRepeat(x,y,option) arguments (Repeating) x double y double option {mustBeMember(option,["linear","cubic"])} end % Function code % Return cell arrays xCell = x; yCell = y; optionCell = option; end
Можно вызвать функцию без входных параметров или множителей трех входных параметров. MATLAB создает массив ячеек для каждого аргумента, содержащего все передачи значений для того аргумента. Этот вызов fRepeat
передачи два набора трех повторяющихся аргументов.
[xCell,yCell,optionCell] = fRepeat(1,2,"linear",3,4,"cubic")
xCell = 1×2 cell array {[1]} {[3]} yCell = 1×2 cell array {[2]} {[4]} optionCell = 1×2 cell array {["linear"]} {["cubic"]}
Следующая функция принимает повторяющиеся аргументы для x
и y
входные параметры в Repeating
arguments
блок. В теле функции значения задали, когда повторяющиеся аргументы доступны в массивах ячеек x
и y
. Этот пример чередует значения x
и y
совпадать с необходимым входом к plot
функция: plot(x1,y1,…)
.
function myPlotRepeating(x,y) arguments (Repeating) x (1,:) double y (1,:) double end % Function code % Interleave x and y z = reshape([x;y],1,[]); % Call plot function if ~isempty(z) plot(z{:}); end end
Вызовите эту функцию с повторяющимися парами входных параметров.
x1 = 1:10; y1 = sin(x1); x2 = 0:5; y2 = sin(x2); myPlotRepeating(x1,y1,x2,y2)
varargin
для повторения аргументовИспользуя varargin
с функциями, которые используют валидацию аргумента, не рекомендуется. Если varargin
ограничивается в размере или классе в повторяющемся блоке аргументов, затем ограничения применяются ко всем значениям в varargin
.
Если вы используете varargin
чтобы поддержать унаследованный код, это должен быть единственный аргумент в Repeating
arguments
блок.
Например, эта функция задает два необходимых позиционных параметра и varargin
в качестве повторяющегося аргумента.
function f(a, b, varargin) arguments a uint32 b uint32 end arguments (Repeating) varargin end % Function code ... end
Аргументы значения имени сопоставляют имя со значением, которое передается функции. Аргументы значения имени:
Может быть передан функции в любом порядке
Являются всегда дополнительными
Должен быть объявлен после всех позиционных и повторяющихся аргументов
Не может появиться в arguments
блокируйтесь, который использует Repeating
атрибут
Должен использовать уникальные имена даже когда с помощью нескольких структур значения имени
Не может использовать имена, которые также используются для позиционных параметров
Объявите аргументы значения имени в arguments
блокируйте запись через точку использования, чтобы задать поля структуры. Например, структура под названием NameValueArgs
задает два аргумента значения имени, Name1
и Name2
. Можно использовать любой допустимый идентификатор MATLAB в качестве имени структуры.
arguments NameValueArgs.Name1 NameValueArgs.Name2 end
Имя структуры должно появиться в функциональной подписи.
function myFunction(NameValueArgs)
Вызовите функцию с помощью имен полей в структуре значения имени, переданной как строка или вектор символов.
myFunction('Name1',value1,'Name2',value2)
Имя структуры, используемой в функциональной подписи, является именем структуры в функциональной рабочей области, которая содержит имена, и значения передали функции.
function result = myFunction(NameValueArgs) arguments NameValueArgs.Name1 NameValueArgs.Name2 end % Function code result = NameValueArgs.Name1 * NameValueArgs.Name2; end
r = myFunction('Name1',3,'Name2',7)
r = 21
Можно задать значение по умолчанию для каждого имени. Если вы не задаете значение по умолчанию, и функция вызвана без того аргумента значения имени, то то поле не присутствует в структуре значения имени. Если никакие аргументы значения имени не передаются функции, MATLAB создает структуру, но это не имеет никаких полей.
Чтобы определить, какие аргументы значения имени были переданы в вызове функции, используйте isfield
функция.
Например, следующая функция задает два необходимых позиционных параметра (width
и height
) и два аргумента значения имени (LineStyle
и LineWidth
). В этом примере, options
структура имеет два поля (LineStyle
и LineWidth
) содержа или значения по умолчанию или значения, заданные в качестве аргументов значения имени, когда функция вызвана.
function myRectangle(width,height,options) arguments width double height double options.LineStyle (1,1) string = "-" options.LineWidth (1,1) {mustBeNumeric} = 1 end % Function code ... end
Все следующее является допустимыми способами вызвать эту функцию.
myRectangle(4,5) myRectangle(4,5,"LineStyle",":","LineWidth",2) myRectangle(4,5,"LineWidth",2,"LineStyle",":") myRectangle(4,5,"LineStyle",":") myRectangle(4,5,"LineWidth",2)
Если функция задает повторяющиеся аргументы, то необходимо объявить аргументы значения имени в отдельном arguments
блокируйтесь, который следует за повторяющимся блоком аргументов. Например, эта функция принимает два повторяющихся аргумента, x
и y
. После определения всех повторений x
и y
, можно задать пару "имя-значение", которая присваивает значение lin
или log
к PlotType
имя.
Определить, включает ли вызов функции PlotType
аргумент, используйте isfield
функционируйте, чтобы проверять на PlotType
поле в scale
структура.
function linLog(x,y,scale) arguments(Repeating) x (1,:) double y (1,:) double end arguments scale.PlotType (1,1) string end z = reshape([x;y],1,[]); if isfield(scale,"PlotType") if scale.PlotType == "lin" plot(z{:}) elseif scale.PlotType =="log" loglog(z{:}) end end end
Вызовите эту функцию с или без аргумента значения имени.
myLinLog(1:5,1:5) myLinLog(1:5,1:5,1:10,1:100:1000) myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")
Блоки аргумента функции могут содержать несколько структур значения имени. Однако имена полей должны быть уникальными среди всех структур. Эта функция имеет две структуры значения имени: lineOptions
и fillOptions
. Эти структуры не могут иметь тех же имен полей.
Аргументы в myRectangle
функция:
width
и height
требуемые позиционные параметры типа double
.
lineOptions.LineStyle
скалярная строка со значением по умолчанию "-"
.
lineOptions.LineWidth
скаляр, числовой со значением по умолчанию 1
.
fillOptions.Color
строка.
fillOptions.Pattern
не имеет никаких ограничений на его значение.
function myRectangle(width,height,lineOptions,fillOptions) arguments width double height double lineOptions.LineStyle (1,1) string = "-" lineOptions.LineWidth (1,1) {mustBeNumeric} = 1 fillOptions.Color string fillOptions.Pattern end % Function Code ... end
Полезный синтаксис функций в MATLAB использует публичные свойства класса для имен аргументов значения имени. Задавать аргументы значения имени для всех устанавливаемых свойств, заданных классом (то есть, всех свойств с общедоступным SetAccess
), используйте этот синтаксис в arguments
блок:
structName.?ClassName
Функция может использовать "structName
.?
ClassName
"синтаксис только однажды. Поэтому функция может задать только одну структуру значения имени, которая получает ее имена полей от класса, даже если использование различных классов и структуры называет.
Если класс устанавливает ограничения для значений, которые можно присвоить свойству при помощи валидации свойства, то функция применяет валидацию к отдельным аргументам значения имени. Для получения информации о валидации свойства см. Проверку значений свойств.
Например, эта функция имеет два обязательных аргумента, x
и y
и принимает любое имя общественной собственности и значение для matlab.graphics.chart.primitive.Bar
класс.
function myBar(x,y,propArgs) arguments x (:,:) double y (:,:) double propArgs.?matlab.graphics.chart.primitive.Bar end propertyCell = namedargs2cell(propArgs); bar(x,y,propertyCell{:}) end
Вызовите функцию с необходимыми входными параметрами и любыми устанавливаемыми парами "имя-значение" свойства.
x = [1,2,3;4,5,6]; y = x.^2; myBar(x,y) myBar(x,y,'FaceColor','magenta','BarLayout','grouped')
Можно заменить валидацию свойства класса путем переопределения имени свойства с аргументом значения собственного имени в блоке аргументов.
structName.?ClassName structName.PropertyName (dim1,dim2,...) ClassName {fcn1,fcn2,...}
Валидация аргумента значения собственного имени заменяет валидацию, заданную классом для индивидуально заданного имени свойства.
Например, следующая функция задает аргументы значения имени как свойства matlab.graphics.chart.primitive.Bar
класс. Функция также заменяет имя свойства FaceColor
позволить только эти определенные значения: red
или blue
.
matlab.graphics.chart.primitive.Bar
класс имеет значение по умолчанию для FaceColor
это не одно из ограниченных значений (red
или blue
). Поэтому переопределяющее объявление должно присвоить значение по умолчанию, которое удовлетворяет ограничению, установленному mustBeMember
функция валидации. Таким образом, значением по умолчанию должен быть red
или blue
.
Эта функция преобразует структуру значения имени в массив ячеек, содержащий чередованные имена и значения с помощью namedargs2cell
функция.
function myBar(x,y,propArgs) arguments x (:,:) double y (:,:) double propArgs.?matlab.graphics.chart.primitive.Bar propArgs.FaceColor {mustBeMember(propArgs.FaceColor,{'red','blue'})} = "blue" end propertyCell = namedargs2cell(propArgs); bar(x,y,propertyCell{:}) end
Вызовите функцию с помощью этих двух обязательных аргументов, x
и y
. Опционально передайте любые пары "имя-значение", поддержанные функцией панели и значением для FaceColor
это может быть любой red
или blue
. Другие значения для FaceColor
не позволены.
x = [1,2,3;4,5,6]; y = x.^2; myBar(x,y) myBar(x,y,'FaceColor','red','BarLayout','grouped')
Проверка входных параметров метода полезна в открытых методах, потому что вызовы метода не могут произойти в коде класса. Можно использовать валидацию аргумента функции в методах реального класса, включая конкретные методы, заданные в абстрактных классах. Однако абстрактные методы (методы, не реализованные классом), не могут задать arguments
блоки. Для получения информации о методах класса см. Методы и Абстрактные классы и Члены класса.
Если classdef
файл включает прототипы метода для методов, заданных в отдельных файлах, включайте arguments
блоки в отдельных файлах, задающих метод. Для получения дополнительной информации об определении методов в отдельных файлах см. Методы в Отдельных Файлах.
Методы подклассов не наследовали валидацию аргумента функции. В методах подклассов, которые заменяют методы суперкласса, можно добавить ту же валидацию аргумента в метод подклассов, как используется в методе суперкласса.
Методы деструктора класса Handle не могут использовать валидацию аргумента. Метод под названием delete
в подклассе указателя, который включает arguments
блок не обработан как деструктор. (Другими словами, это не вызвано MATLAB, когда объект уничтожается). Для получения дополнительной информации о методах деструктора класса смотрите Деструктор Класса Handle.
Когда функция вызвана, MATLAB подтверждает входные параметры в порядке, которым они объявляются в arguments
блокируйтесь, сверху донизу. Каждый аргумент полностью подтвержден, прежде чем следующий аргумент подтвержден. Поэтому любая ссылка на ранее заявленный аргумент использует значения, которые были подтверждены. Функции выдают ошибку в результате первого отказа валидации.
Подтвержденные значения могут отличаться от исходных значений, переданных как входные параметры, когда функция вызвана. Например, эта функция объявляет входные параметры как класс uint32
значения. Третье входное объявление присваивает значение по умолчанию, равное продукту первых двух входных параметров.
function c = f(a, b,c) arguments a uint32 b uint32 c uint32 = a .* b end % Function code ... end
Вызывая функцию с входными параметрами, которые являются различным числовым классом (например, double
) результаты в преобразовании в uint32
.
c = f(1.8,1.5)
Поскольку дополнительный входной параметр c
не задан в вызове функции, MATLAB выполняет значение по умолчанию и присваивает его c
после преобразования a
и b
к uint32
значения. В этом случае преобразование приводит к значению 2 для обоих входных параметров. Поэтому продукт a
времена b
четыре.
c = uint32 4
Если вы задаете значение для третьего входа, то функция присваивает значение c
и не выполняет выражение значения по умолчанию.
c = f(1.8,1.5,25)
c = uint32 25
Во время процесса валидации MATLAB применяет класс и затем валидацию размера прежде, чем вызвать любые функции валидации. Если значение по умолчанию используется для дополнительного входа, который не использован в вызове функции, это значение присвоено аргументу прежде, чем применить любые шаги в процессе валидации.
Когда значение аргумента, которое передается функции, не совпадает с классом и размером, требуемым валидацией, MATLAB преобразует значение в заявленный класс и размер, когда преобразование возможно. Однако преобразование не может быть желаемым поведением.
Вот некоторые примеры преобразований, которые может выполнить MATLAB.
Удовлетворить числовому ограничению класса:
char
значение может быть преобразовано в свое числовое значение Unicode®.
string
может быть преобразован в номер или NaN
если строка не является представлением одного номера.
Удовлетворить ограничению размера:
Скалярное расширение может изменить размер от скаляра до нескалярного.
Вектор-столбец может быть преобразован в вектор-строку.
Чтобы устранить стандартные преобразования, выполняемые MATLAB от валидации входного параметра, используйте функции валидации вместо ограничений размера и класса. Вызовы функций валидации не делают возвращаемых значений и не могут изменить значение входного параметра.
Например, эта функция ограничивает первый вход двумерным массивом любого размера, который имеет класс double
. Второй вход должен быть 5 3 массив любого класса.
function f(a, b) arguments a (:,:) double b (5,3) end % Function code ... end
Из-за стандартного преобразования типов MATLAB и скалярного расширения, можно вызвать эту функцию со следующими входными параметрами и не получить ошибку валидации.
f('character vector',144)
По умолчанию MATLAB преобразует элементы вектора символов к их эквивалентному числовому значению и применяет скалярное расширение, чтобы создать 5 3 массив от скалярного значения 144
.
Используя специализированную валидацию функции могут обеспечить более определенную валидацию входного параметра. Например, эта функция задает специализированные функции валидации, которые она использует вместо класса и технических требований размера для первых и вторых аргументов. Эти локальные функции позволяют вам избежать преобразований входного значения.
mustBeOfClass
ограничивает вход определенным классом, не позволяя преобразование или подклассы. Для связанной функции смотрите mustBeA
.
mustBeEqualSize
ограничивает два входных параметров, чтобы иметь равный размер, не позволяя скалярное расширение. Для связанной функции смотрите mustBeScalarOrEmpty
.
mustBeDims
ограничивает вход, чтобы быть заданного измерения, не позволяя перемещение или скалярное расширение. Для связанной функции смотрите mustBeVector
.
function fCustomValidators(a, b) arguments a {mustBeOfClass(a,'double'), mustBeDims(a,2)} b {mustBeEqualSize(b,a)} end % Function code ... end % Custom validator functions function mustBeOfClass(input,className) % Test for specific class name cname = class(input); if ~strcmp(cname,className) eid = 'Class:notCorrectClass'; msg = ['Input must be of class ', cname]; throwAsCaller(MException(eid,msg)) end end function mustBeEqualSize(a,b) % Test for equal size if ~isequal(size(a),size(b)) eid = 'Size:notEqual'; msg = 'Inputs must have equal size.'; throwAsCaller(MException(eid,msg)) end end function mustBeDims(input,numDims) % Test for number of dimensions if ~isequal(length(size(input)),numDims) eid = 'Size:wrongDimensions'; msg = ['Input must have dimensions: ',num2str(numDims)]; throwAsCaller(MException(eid,msg)) end end
mustBeOfClass
функция осуществляет строгий класс, соответствующий путем требования соответствия с именем класса. Более общий подход мог использовать isa
функционируйте, чтобы также совпадать с подклассами заданного класса.
mustBeEqualSize
и mustBeDims
функции осуществляют строгие объявления для входных параметров.
fCustomValidators('character vector',144)
Invalid input argument at position 1. Input must be of class double
В этом вызове количество размерностей первого входа является неправильным, таким образом, функция валидации возвращает пользовательское сообщение об ошибке.
fCustomValidators(ones(2,2,4),144)
Invalid input argument at position 1. Input must have 2 dimensions
mustBeEqualSize
функция блока проверки допустимости ограничивает второй вход определенной размерностью, которая обеспечивается в сообщении об ошибке.
fCustomValidators(ones(2,2),144)
Invalid input argument at position 2. Input must be of size [5 3]
Для связанных предопределенных функций валидации смотрите mustBeA
, mustBeFloat
, и mustBeVector
.
nargin
в валидации аргумента nargin
функция возвращает количество входных аргументов функции, данных в вызове функции выполняющегося в данного момента. При использовании валидации аргумента функции, значение, возвращенное nargin
в функции количество позиционных параметров, обеспеченных, когда функция вызвана.
Повторяющиеся аргументы являются позиционными параметрами, и поэтому количество повторяющихся аргументов передало функции, когда названо включен в значение, возвращенное nargin
.
Значение это nargin
возвращается не включает дополнительные аргументы, которые не включены в вызов функции. Кроме того, nargin
не считает аргументов значения имени.
Использование nargin
определить, передаются ли дополнительные позиционные параметры функции, когда названо. Например, эта функция объявляет три позиционных параметра и аргумент значения имени. Вот то, как функция определяет, какие аргументы передаются, когда она называется.
function result = fNargin(a, b, c, namedargs) arguments a (1,1) double b (1,1) double c (1,1) double = 1 namedargs.Format (1,:) char end % Function code switch nargin case 2 result = a + b; case 3 result = a^c + b^c; end if isfield(namedargs,'Format') format(namedargs.Format); end end
В этом вызове функции, значении nargin
2
:
result = fNargin(3,4)
result = 7
В этом вызове функции, значении nargin
3
:
result = fNargin(3,4,7.62)
result = 4.3021e+04
В этом вызове функции, значении nargin
3:
result = fNargin(3,4,7.62,'Format','bank')
result = 43020.56
arguments
блоки существуют в рабочей области функции. Любые пакеты, классы или функции, добавленные к осциллографу функции с помощью import
команда добавляется к осциллографу arguments
блок.
Единственные переменные, видимые к функциям блока проверки допустимости и выражениям значения по умолчанию, являются входными переменными, уже объявленными. В этой функции, значении по умолчанию c
выведен из a
и b
.
function c = f(a,b,c) arguments a uint32 b uint32 c uint32 = a * b end % Function code ... end
Однако вы не можете обратиться к входным переменным, еще не объявленным в arguments
блок. Например, с помощью этого объявления для аргумента a
в предыдущей функции не допустимо потому что b
и c
еще не были объявлены.
arguments a uint32 = b * c b uint32 c uint32 end
Выражения валидации аргумента могут сослаться только ранее объявленный, и поэтому подтвержденный, аргументы. Функции валидации и значения по умолчанию для аргументов значения имени не могут получить доступ к другим аргументам значения имени.
arguments
БлокЛюбые ссылки на ранее заявленные аргументы должны отобразиться в тексте функций валидации и значений по умолчанию. Чтобы гарантировать прозрачность по коду, не используйте функции, которые взаимодействуют с функциональной рабочей областью. А именно, не используйте вложенные функции или любую из функций, перечисленных в следующей таблице в arguments
блок.
assignin | builtin | clear |
dbstack | eval | evalc |
evalin | exist | feval |
input | inputname | load |
nargin | narginchk | nargoutchk |
save | whos | who |
Эти ограничения применяются только в arguments
блокируйтесь и не обращайтесь к переменным или функциям в теле функции.