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

Введение в валидацию аргументов

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

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

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

Где использовать валидацию аргументов

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

arguments Синтаксис блоков

Функции определяют валидацию аргументов в кодовых блоках, которые разграничены ключевыми словами arguments и end. Если используется, arguments блок должен стартовать перед первой исполняемой линией функции.

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

Выделенная область в следующем коде показывает синтаксис для валидации аргумента.

Объявление аргумента функции может включать в себя любой из следующих видов ограничений:

Можно также задать значение по умолчанию для входного параметра в объявлении проверки функции для этого аргумента. Значение по умолчанию должно удовлетворять объявленным ограничениям для этого аргумента.

A(indices) = value

Примеры валидации аргументов

Этот arguments блок задает размер и класс трёх входов.

function out = myFunction(A, B, C)   
    arguments
        A (1,1) string 
        B (1,:) double
        C (2,2) cell
    end

    % Function code
    ...
end

В этой функции переменные должны удовлетворять этим требованиям валидации:

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

forwardSpeed(int8(4),"A string",'full')

double
char
SpeedEnum

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.

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 для каждого повторения должен быть включен блок.

Для примера, если a 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)

function f(a, b, varargin)
    arguments
        a uint32
        b uint32
    end
    arguments (Repeating)
        varargin
    end
    
    % Function code
    ...
end

Аргументы в виде имя-значение

Аргументы имя-значение связывают имя со значением, которое передается функции. Аргументы имя-значение:

Объявление аргументов имя-значение в arguments блокируйте использование записи через точку для определения полей структуры. Для примера структура с именем NameValueArgs задает два аргумента в виде имя-значение, Name1 и Name2. В качестве имени структуры можно использовать любой допустимый идентификатор MATLAB.

arguments
    NameValueArgs.Name1
    NameValueArgs.Name2
end

Имя структуры должно находиться в сигнатуре функции.

function myFunction(NameValueArgs)

Вызовите функцию, используя имена полей в структуре имя-значение.

myFunction(Name1=value1,Name2=value2)

Перед R2021a передайте имена как строки или векторы символов, а также разделите имена и значения запятыми. Оба синтаксиса действительны в более поздних релизах.

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

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

Аргументы имя-значение поддерживают частичное совпадение имен, когда нет неоднозначности. Для примера - функция, которая задает LineWidth и LineStyle как его два аргумента в виде имя-значение принимают LineW и LineS, но использование Line приводит к ошибке. В целом использование полных имен является рекомендуемой практикой, чтобы улучшить читаемость кода и избежать неожиданного поведения.

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)

myRectangle(4,5,"LineStyle",":","LineWidth",2)
myRectangle(4,5,"LineWidth",2,"LineStyle",":")

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")

myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")

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")

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

myBar(x,y,"FaceColor","magenta","BarLayout","grouped")

structName.?ClassName
structName.PropertyName (dim1,dim2,...) ClassName {fcn1,fcn2,...}

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 = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="red",BarLayout="grouped")

Валидация аргументов в методах классов

Проверка входных параметров метода полезна в общедоступных методах, поскольку вызовы метода могут не происходить в коде класса. Валидацию аргументов функции можно использовать в конкретных методах классов, включая конкретные методы, определенные в абстрактных классах. Однако абстрактные методы (методы, не реализованные классом) не могут определять arguments блоки. Для получения информации о методах классов см. Методы и абстрактные классы и члены класса.

Если a classdef файл включает прототипы методов, определенных в отдельных файлах, включая arguments блоки в отдельных файлах, определяющих метод. Для получения дополнительной информации об определении методов в отдельных файлах, см. Методы в отдельных файлах.

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

Методы уничтожения классов Handle не могут использовать валидацию аргументов. Метод с именем delete в подклассе указателя, который включает в себя arguments блок не рассматривается как деструктор. (Другими словами, он не вызывается MATLAB, когда объект уничтожается). Для получения дополнительной информации о методах разрушения классов смотрите Класс Handle Destructor.

Порядок валидации аргументов

Когда вызывается функция, 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 может выполнить.

Чтобы удовлетворить ограничению числового класса:

Чтобы удовлетворить ограничению размера:

Чтобы исключить стандартные преобразования, выполненные 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.

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

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 Функция validator ограничивает второй вход определенной размерностью, которое предусмотрено в сообщении об ошибке.

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

Выражения валидации аргументов могут ссылаться только на ранее объявленные и, следовательно, проверенные аргументы. Функции валидации и значения по умолчанию для аргументов имя-значение не могут получить доступ к другим аргументам имя-значение.

Блоки отладки аргументов

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