arguments

Объявить валидацию аргумента функции

Синтаксис

arguments
    argName1 (dimensions) dataType {validators} = defaultValue
    ...
    argNameN ...
end

arguments (Repeating)
    ... 
end

Описание

пример

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

Каждый аргумент может иметь одно или несколько ограничений или значение по умолчанию, как показано на этом синтаксисе:

argName (dimensions) dataType {validators} = defaultValue

  • (dimensions) - Размер входа, заданный как разделенный списками , разделенными запятыми из двух или более чисел, таких как (1,2), (3,5,2), или (1,:). Двоеточие допускает любую длину в этой размерности. (dimensions) не может включать выражения.

    Размерности входов должны совпадать (dimensions) точно или быть compatible с размером, заданным (dimensions). Для примера, (1,:) задает, что входной параметр должен быть вектором-строкой n 1 байт, но вектор-столбец n -by-1 совместим. Функция изменяет форму вектора-строки входа на вектор-столбец. Точно так же размер (2,3) позволяет скалярный вход, но он расширяет вход до матрицы 2 на 3. Дополнительные сведения см. в разделе «Совместимые размеры массивов для основных Операций».

  • dataType - Тип данных, заданный как имя класса, например double. Входной вход должен быть заданным типом или типом, который может быть преобразован в этот тип. Для примера - функция, которая задает double принимает значения типа single и преобразует их в double.

  • {validators} - Разделенный запятыми список функций валидации, таких как mustBeNumeric и mustBeScalarOrEmpty, заключенный в фигурные кронштейны. Ошибка функций валидации, когда входные параметры не соответствуют их условиям. В отличие от dataType, функции валидации не изменяют входные параметры. Список функций валидации см. в разделе Функции валидации аргументов.

  • defaultValue - Значения по умолчанию должны соответствовать указанному размеру, типу и правилам валидации. Значение по умолчанию также может быть выражением. Установка значения по умолчанию делает аргумент необязательным. Необязательные аргументы должны располагаться после требуемых аргументов в сигнатуре функции и в arguments блок.

Для аргументов имя-значение, arg использует форму nv.name, где nv - имя структуры в сигнатуре функции и name - имя аргумента в блоке аргументов. Например, задайте функцию, которая принимает аргументы имя-значение с помощью структуры с именем options.

y = myFunction(x,options)

В блоке аргументов задайте имена для аргументов имя-значение как поля:

arguments 
    x
    options.Name1
    options.Name2
end 

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

arguments (Repeating) ... end объявляет повторяющиеся аргументы.

Для примера, если вы создаете функцию с именем myplot с повторяющимися аргументами X, Y, и styleфункция принимает несколько наборов из этих трех аргументов, таких как myplot(x1,y1,style1,x2,y2,style2). MATLAB® создает массив ячеек, содержащий все значения, переданные для этого аргумента.

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

Дополнительные сведения о повторении аргументов см. в разделе Повторение аргументов.

Примеры

свернуть все

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

function [m,s] = twoStats(x)
    arguments
        x (1,:) {mustBeNumeric}
    end
    m = mean(x,"all");
    s = std(x,1,"all");
end

Вызовите функцию на трехэлементном векторе-строке.

a = [1 3 5];
[m,s] = twoStats(a)
m =

     3


s =

    1.6330

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

a = [1 3 5]';
[m,s] = twoStats(a)
m =

     3


s =

    1.6330

Если вы вызываете функцию с вектором, который содержит нечисловые значения, mustBeNumeric Функция валидации выдает ошибку.

a = ["1" "3" "5"];
[m,s] = twoStats(a)
Error using twoStats
Invalid argument at position 1. Value must be numeric.

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

Объявить myRectangle функция со options как имя структуры. Два поля options, LineStyle и LineWidth, являются именами в аргументах имя-значение функции:

function myRectangle(X,Y,options)
    arguments
       X double
       Y 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 передайте имена как строки или векторы символов, а также разделите имена и значения запятыми. Оба синтаксиса действительны в более поздних релизах.

Повторяющиеся аргументы являются отдельными аргументами или группами аргументов, которые могут быть повторены в нуле или более раз в вызове функции. fRepeat функция принимает повторяющиеся группы аргументов x, y, и style. Ограничьте входные параметры x и y в векторы двойных значений или значений, преобразуемых в двойные. Ограничение style к строкам "--" и ":" .

function fRepeat(x,y,style)
    arguments (Repeating)
        x (1,:) double
        y (1,:) double
        style {mustBeMember(style,["--",":"])}       
    end
    
    % Reshape the cell arrays of inputs and call plot function
    z = reshape([x;y;style],1,[]);
    if ~isempty(z)
        plot(z{:});
    end
end

Звонить fRepeat с двумя группами входов. MATLAB создает массив ячеек, содержащий все значения, переданные для x, другой массив для значений y, и треть для значений style. Затем функция изменяет форму этих массивов в массив ячеек 1 на 6, z, и передает его в plot.

x1 = 1:10;
y1 = 1:10; 
s1 = ":"; 
x2 = 1:7;
y2 = 1:1.5:10;
s2 = "--";
fRepeat(x1,y1,s1,x2,y2,s2)

Plot showing two lines

Ограничения

  • Блоки аргументов не поддерживаются во вложенных функциях, абстрактных методах или классе Handle методах деструктора.

Подробнее о

свернуть все

Поддерживаемые типы данных

Объявления аргументов могут задавать любой класс MATLAB или внешне определенный класс, который поддерживается MATLAB, кроме классов Java, классов COM и классов MATLAB, определенных до MATLAB версии 7.6 (другими словами, определений классов, которые не используют classdef ключевое слово).

Совет

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

    function y = myFunction(inputArg1)
        arguments
            inputArg1 (1,1) double
        end
        ...
    Для этой функции, если вы передаете строку "123" как входной параметр, MATLAB преобразует строку в числовое значение 123 типа double.

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

    • Чтобы избежать преобразования строк в числовые значения, используйте mustBeA, mustBeFloat, или mustBeNumeric.

    • Чтобы избежать преобразования числовых значений в строки, используйте mustBeText, mustBeTextScalar, или mustBeNonZeroLengthText.

    • Чтобы избежать преобразования размера, используйте mustBeVector или mustBeScalarOrEmpty.

Введенный в R2019b