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

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

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

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

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

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

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

arguments Блокируйте синтаксис

Валидация аргумента define функций в блоках кода, которые разграничены ключевыми словами 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 блок должен быть включен для каждого повторения.

Например, если Repeating arguments блок задает аргументы x и y, затем каждое повторение должно содержать оба x и y.

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

Функции должны объявить повторяющиеся аргументы после позиционных параметров и перед аргументами name-value. Вы не можете задать аргументы name-value в Repeating блок. Для получения информации об аргументах name-value смотрите Аргументы name-value.

В функции каждый аргумент повторения становится массивом ячеек с числом элементов, равным количеству повторений, переданных в вызове функции. Валидация применяется к каждому элементу массива ячеек. Если функция вызвана с нулевыми случаями этого аргумента, массив ячеек имеет размер 1 на 0. Таким образом, это пусто.

Например, эта функция объявляет блок трех повторяющихся аргументов, xY, и 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

Аргументы name-value

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

Объявите аргументы name-value в arguments блокируйте запись через точку использования, чтобы задать поля структуры. Например, структура под названием NameValueArgs задает два аргументов name-value, 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

Аргументы name-value поддерживают частичное соответствие имени, когда нет никакой неоднозначности. Например, функция, которая задает LineWidth и LineStyle как его два аргументов name-value принимает 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 myLinLog(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

Устойчивая обработка аргументов name-value

Лучшая практика для реализации аргументов name-value в ваших функциях путем определения их в блоке аргументов. Блок аргументов избавляет от необходимости писать ваш собственный код, чтобы проанализировать аргументы name-value, и блок также помогает реализовать устойчивый парсинг аргумента для обоих "name",value синтаксис и name=value синтаксис введен в R2021a.

myFunction(data,"allow-empty",true)

function mySignal(tag,unit,opts)
    arguments
        tag = "0"
        unit = "ampere"
        opts.Magnifier {mustBeMember{opts.Magnifier,["small","medium","big"]}}
    end
end

mySignal("Mag","coulomb")

function mySignal(tag,unit,opts)
    arguments
        tag
        unit = "ampere"
        opts.Magnifier {mustBeMember{opts.Magnifier,["small","medium","big"]}}
    end
end

Аргументы name-value из свойств класса

Полезный синтаксис функций в MATLAB использует публичные свойства класса для имен аргументов name-value. Задавать аргументы name-value для всех устанавливаемых свойств, заданных классом (то есть, всех свойств с общедоступным SetAccess), используйте этот синтаксис в arguments блок:

structName.?ClassName

Функция может использовать "structName.? ClassName"синтаксис только однажды. Поэтому функция может задать только одну структуру значения имени, которая получает ее имена полей от класса, даже если использование различных классов и структуры называет.

Если класс устанавливает ограничения для значений, которые можно присвоить свойству при помощи валидации свойства, то функция применяет валидацию к отдельным аргументам name-value. Для получения информации о валидации свойства см. Проверку значений свойств.

Например, эта функция имеет два обязательных аргумента, 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 блоки. Для получения информации о методах класса см. Методы и Абстрактные классы и Члены класса.

Если 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.

Удовлетворить числовому ограничению класса:

Удовлетворить ограничению размера:

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

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 не считает аргументов name-value.

Использование 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

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

Отладка блоков аргументов

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