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

Введение в проверку аргументов

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

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

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

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

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

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

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

При вызове функции 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 не считает аргументы «имя-значение».

Использовать 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.

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

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