Валидация аргумента функции

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

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

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

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

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

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

  1. Необходимые позиционные параметры

  2. Дополнительные позиционные параметры

  3. Повторение позиционных параметров

  4. Дополнительные аргументы значения имени

Требуемые и дополнительные позиционные параметры

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

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

Избегайте использования 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)

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

Значения по умолчанию для аргументов значения имени

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

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

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

Используя аргументы повторения и значения имени

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

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

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

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

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

  • nargin определяет если дополнительный позиционный параметр c передается функции с a switch блок.

  • isfield определяет если аргумент значения имени для Format передается функции.

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 блок.

assigninbuiltinclear
dbstackevalevalc
evalinexistfeval
inputinputnameload
narginnarginchknargoutchk
savewhoswho

Эти ограничения применяются только в arguments блокируйтесь и не обращайтесь к переменным или функциям в теле функции.

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

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

Смотрите также

|

Похожие темы

Для просмотра документации необходимо авторизоваться на сайте