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,:) указывает, что вход должен быть 1 n вектором-строкой, но 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 блоки в целом, смотрите аргументы Block Syntax.

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

Например, если вы создаете функцию с именем myplot с повторяющимися аргументами XY, и 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 функция принимает повторяющиеся группы аргументов xY, и 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, заданных перед Версией 7.6 программного обеспечения MATLAB (другими словами, определения классов, которые не используют classdef ключевое слово).

Советы

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

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

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

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

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

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

Введенный в R2019b