이 번역 페이지는 최신 내용을 담고 있지 않습니다. 최신 내용을 영문으로 보려면 여기를 클릭하십시오.

함수 인수 유효성 검사

인수 유효성 검사 소개

함수 인수 유효성 검사는 함수 인수에 대한 특정 제한을 선언하는 한 가지 방법입니다. 인수 유효성 검사를 사용하면 함수 본문에 테스트를 수행하는 코드를 작성하지 않고도 인수의 클래스, 크기 및 그 밖의 특성을 제한할 수 있습니다.

함수 인수 유효성 검사는 선언적이기 때문에 이 검사를 사용하면 MATLAB^® 데스크탑 툴에서 특정 코드 블록을 검토하여 함수에 대한 정보를 추출할 수 있습니다. 인수에 대한 요구 사항을 선언하여 복잡한 인수 확인 코드를 제거하고 코드의 가독성, 견고성 및 유지 관리성을 향상시킬 수 있습니다.

함수 인수 유효성 검사 구문은 선택적 인수 , 반복되는 인수, 이름-값 인수를 정의하는 절차를 간소화합니다. 또한 이 구문은 일관된 방법으로 디폴트 값을 정의할 수 있도록 합니다.

인수 유효성 검사를 사용하는 경우

함수 정의에서 함수 인수 유효성 검사의 사용 여부는 선택 사항입니다. 인수 유효성 검사는 어떤 코드로도 호출할 수 있으며, 함수 코드 실행 전에 인수의 유효성을 확인해야 하는 함수에서 가장 유용합니다. 다른 곳에서 이용할 수 있도록 설계된 함수의 경우, 인수에 대해 적합한 수준의 제한을 적용하고 인수 유효성 검사에 기반하여 특정 오류 메시지를 반환하는 수단으로 이 검사를 활용할 수 있습니다.

유효성 검사가 필요하지 않은 경우

로컬 함수와 프라이빗 함수, 프라이빗 메서드와 보호 메서드에서는 호출자가 입력 요구 사항을 알고 있기 때문에 유효한 인수로 이러한 유형의 함수를 호출할 수 있습니다.

유효성 검사가 허용되지 않는 경우

중첩 함수, 추상 메서드 또는 핸들 클래스 소멸자 메서드에서는 인수 유효성 검사 구문을 사용할 수 없습니다. 메서드에서의 인수 유효성 검사에 대한 자세한 내용은 메서드 구문 항목을 참조하십시오.

arguments 블록 구문

함수는 키워드 arguments와 end로 구분된 선택적 코드 블록에 인수 유효성 검사를 정의합니다. 사용할 경우, arguments 블록은 함수의 실행 가능한 첫 번째 라인 전에 시작되어야 합니다.

함수에 여러 개의 arguments 블록을 사용할 수 있지만 모든 블록은 arguments 블록의 일부가 아닌 코드 앞에 있어야 합니다.

다음 코드에서 강조 표시된 영역이 입력 인수 유효성 검사를 위한 구문입니다.

함수 인수 선언에는 다음 종류의 제한 사항이 포함될 수 있습니다.

• 크기 — 각 차원의 길이로, 괄호로 묶습니다.

• 클래스 — 단일 MATLAB 클래스의 이름입니다.

• 함수 — 쉼표로 구분된 유효성 검사 함수 목록으로, 중괄호로 묶습니다.

또한 입력 인수의 디폴트 값을 해당 인수에 대한 함수 유효성 검사 선언에 정의할 수 있습니다. 디폴트 값은 해당 인수에 대해 선언된 제한 사항을 충족해야 합니다.

크기

유효성 검사 크기는 인수의 차원으로, 음이 아닌 정수 또는 콜론(:)으로 지정됩니다. 콜론은 그 차원에서 임의의 길이가 허용됨을 나타냅니다. 차원에는 표현식을 사용할 수 없습니다. 함수 호출의 인수에 할당된 값은 지정된 크기와 호환되어야 합니다. 그렇지 않으면 MATLAB이 오류를 발생시킵니다.

MATLAB 인덱스 참조 값 할당 규칙이 크기 사양에 적용됩니다. 예를 들어, MATLAB은 스칼라 확장을 적용하기 때문에 1×1 값이 (5,3)으로 지정된 크기와 호환됩니다. 또한 (1,:)으로 지정된 크기가 1×n 및 n×1의 크기를 받을 수 있도록 MATLAB 행-열 변환이 적용됩니다.

다음은 몇 가지 예입니다.

• (1,1) — 입력값은 정확하게 1×1이어야 합니다.

• (3,:) — 첫 번째 차원은 3이어야 하고, 두 번째 차원은 어떤 값이든 가능합니다.

크기를 지정하지 않으면 유효성 검사 함수가 제한하지 않는 한 어떤 크기도 허용됩니다.

클래스

유효성 검사 클래스는 단일 클래스의 이름입니다. 함수 입력값에 할당된 값은 지정된 클래스이거나 지정된 클래스로 변환될 수 있어야 합니다. 임의의 MATLAB 클래스 또는 MATLAB이 지원하는 외부에서 정의된 클래스를 사용하십시오. 단, Java, COM 클래스 및 classdef 키워드를 사용하지 않는 MATLAB 클래스 정의(MATLAB 버전 7.6 이전에 정의된 클래스)는 예외입니다.

다음은 몇 가지 예입니다.

• char — 입력값은 char 클래스 또는 MATLAB이 char형으로 변환할 수 있는 값(예: string형)이어야 합니다.

• double — 입력값은 모든 정밀도의 숫자형 값일 수 있습니다.

• cell — 입력값은 셀형 배열이어야 합니다.

• 사용자 정의 클래스

클래스를 지정하지 않으면 유효성 검사 함수가 제한하지 않는 한 어떤 클래스도 허용됩니다.

유효성 검사 함수

유효성 검사 함수는 특정 요구 사항이 인수 값으로 충족되지 않으면 오류를 발생시키는 MATLAB 함수입니다. 유효성 검사 함수는 값을 반환하지 않으며, 클래스 및 크기와 달리 유효성을 검사하는 인수의 값을 변경할 수 없습니다.

유효성 검사 과정에서 MATLAB은 해당 인수에 대해 나열된 각각의 유효성 검사 함수에 인수 값을 전달합니다. 유효성 검사 함수에 전달되는 값은 클래스 및 크기 사양에 의한 변환의 결과입니다. MATLAB은 왼쪽부터 오른쪽으로 각 함수를 호출하고 첫 번째로 만나는 오류를 발생시킵니다.

미리 정의된 유효성 검사 함수 표는 인수 유효성 검사 함수 항목을 참조하십시오.

디폴트 값

입력 인수의 디폴트 값은 크기, 클래스 및 유효성 검사 함수 요구 사항을 충족하는 임의의 상수 또는 표현식이 될 수 있습니다. 인수 선언에서 디폴트 값을 지정하면 인수는 선택 사항이 됩니다. 인수가 함수 호출에 포함되어 있지 않으면 MATLAB은 디폴트 값을 사용합니다. 디폴트 값이 사용될 때마다 디폴트 값 표현식이 실행됩니다.

참고

MATLAB은 함수가 인수 값 없이 호출될 때만 디폴트 값의 유효성을 검사하기 때문에, 함수가 해당 인수 없이 호출되는 경우에만 유효하지 않은 디폴트 값으로 인해 오류가 발생합니다.

선택적 인수는 함수 시그니처와 arguments 블록에서 필수 인수 뒤에 위치해야 합니다. 선택적 인수에 대한 자세한 내용은 필수 위치 인수와 선택적 위치 인수 항목을 참조하십시오.

유효성 검사 시퀀스

인수의 유효성 검사는 arguments 블록에서 위에서 아래로 진행됩니다. MATLAB은 특정 순서로 인수 선언의 각 부분에 대해 유효성을 검사합니다. 먼저 클래스의 유효성을 검사한 다음, 크기의 유효성을 검사합니다. 클래스 및 크기 유효성 검사 결과는 유효성 검사 함수로 전달됩니다. 클래스, 크기 및 유효성 검사 함수가 인수 선언에 있는지 여부에 따라 각 단계는 선택 사항이 됩니다.

자세한 내용은 인수 유효성 검사 순서 항목을 참조하십시오.

선언된 클래스 및 크기로의 변환

클래스 유효성 검사와 크기 유효성 검사 모두 인수 값을 변경할 수 있습니다. 다음은 MATLAB이 수행할 수 있는 변환의 몇 가지 예입니다.

클래스 제한 사항을 충족하기 위해:

• char형 값을 string형 값으로 변환할 수 있습니다.

• single형 값을 double형으로 변환할 수 있습니다.

크기 제한 사항을 충족하기 위해:

• 스칼라 확장을 통해 입력값 크기를 스칼라에서 비 스칼라로 변경할 수 있습니다.

• 열 벡터를 행 벡터로 변환할 수 있습니다.

그 결과, 함수 본문에 있는 유효성이 검사된 값은 함수 호출 시 전달된 값과 다를 수 있습니다. 클래스 변환에 대한 자세한 내용은 Implicit Class Conversion 항목을 참조하십시오. 유효성 검사 동안 클래스와 크기 변환을 방지하려면 인수 유효성 검사 함수를 대신 사용하십시오. 자세한 내용은 클래스 및 크기 변환 방지하기 항목을 참조하십시오.

출력 인수 유효성 검사

R2022b부터 출력 인수에 인수 유효성 검사를 사용할 수 있습니다. 입력 인수와 마찬가지로, 출력 인수의 클래스와 크기에 대해 유효성을 검사하고 유효성 검사 함수도 적용할 수 있습니다. 그러나 출력 인수의 디폴트 값을 지정하거나 이전에 선언된 인수를 참조할 수 없습니다. 출력 인수 유효성 검사는 항상 선택 사항입니다. 출력 인수 유효성 검사를 추가하면 코드 가독성이 높아지고, 코드에서 시간에 따라 변할 수 있는 출력값이 일관되게 유지됩니다.

입력 인수와 출력 인수에 대한 유효성을 검사할 때는 별도의 arguments 블록을 사용해야 합니다. arguments 명령문 다음에 arguments 블록 (Input) 또는 (Output)의 유형을 정의하십시오. (Input) arguments 블록과 (Output) arguments 블록이 모두 사용되는 경우, (Output) 블록은 (Input) 블록을 따라야 합니다. 지정된 유형이 없는 경우 MATLAB은 블록에 입력 인수가 포함되어 있다고 간주합니다.

자세한 내용은 arguments 항목을 참조하십시오.

인수 유효성 검사 예제

기본 인수 유효성 검사

다음 arguments 블록은 입력값 3개의 크기와 클래스를 지정합니다.

function out = myFunction(A, B, C)   
    arguments
        A (1,1) string 
        B (1,:) double
        C (2,2) cell
    end

    % Function code
    ...
end

이 함수에서 변수는 다음과 같은 유효성 검사 요구 사항을 충족해야 합니다.

• A는 string형 스칼라입니다.

• B는 1×임의 길이의 double형 벡터입니다.

• 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는 허용된 선택 옵션 3개 중 하나인 문자형 벡터여야 합니다. 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

사용자 지정 유효성 검사 함수 내에는 함수 인수 유효성 검사를 사용하지 마십시오. 유효성 검사 함수 정의에 대한 자세한 내용과 미리 정의된 유효성 검사 함수 목록은 인수 유효성 검사 함수 항목을 참조하십시오.

출력 인수 유효성 검사

R2022b부터 출력 인수에 인수 유효성 검사를 사용할 수 있습니다.

예를 들어, 다음 함수는 별개의 arguments 블록을 사용하여 3개 입력 인수와 한 개 출력 인수의 크기와 클래스에 대한 유효성을 검사합니다. 참고로, (Input) 블록은 (Output) 블록 앞에 와야 합니다.

function out = myFunction(A, B, C)   
    arguments (Input)
        A (1,1) string 
        B (1,:) double
        C (2,2) cell
    end

    arguments (Output)
        out (1,:) double
    end

    % Function code
    ...
end

인수 종류

함수 인수 유효성 검사는 네 가지 종류의 인수를 선언할 수 있습니다. 함수는 다음과 같은 인수를 정의할 수 있지만 아래 순서대로 인수를 정의해야 합니다.

1. 필수 위치 인수

2. 선택적 위치 인수

3. 반복되는 위치 인수

4. 선택적 이름-값 인수

필수 위치 인수와 선택적 위치 인수

위치 인수는 특정 순서로 함수에 전달되어야 합니다. 인수 목록에서 전달된 값의 위치는 arguments 블록에 인수가 선언된 순서와 일치해야 합니다. arguments 블록의 모든 인수 이름은 고유해야 합니다.

인수가 디폴트 값을 정의하지 않는 한 함수를 호출할 때 arguments 블록의 위치 인수가 필요합니다. MATLAB은 함수 호출에서 어떤 값도 전달되지 않을 경우 디폴트 값을 사용할 수 있기 때문에, 인수 선언에 디폴트 값을 지정하면 위치 인수가 선택 사항이 됩니다.

디폴트 값은 상수이거나 인수 선언을 충족하는 결과를 생성하는 표현식이 될 수 있습니다. 표현식은 arguments 블록에서 표현식 앞에 선언된 인수를 참조할 수 있지만 표현식 뒤에 선언된 인수는 참조할 수 없습니다.

MATLAB은 함수 호출에 인수가 포함되지 않은 경우에만 디폴트 값 표현식을 실행합니다.

모든 선택적 인수는 arguments 블록에서 모든 필수 인수 뒤에 위치해야 합니다. 예를 들어, 다음 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에서는 인수 대신 물결표 문자(~)를 전달하여 인수를 무시할 수 있습니다. 함수 시그니처에서의 인수 위치에 대응하는 arguments 블록에서 물결표 문자(~)를 추가하여 사용되지 않는 위치 인수를 무시하는 함수를 정의할 수 있습니다. 함수 시그니처에서 무시된 각 인수에 대해 물결표 문자(~)를 추가하십시오.

무시된 인수는 디폴트 값을 가지거나 클래스, 크기 또는 유효성 검사 함수를 지정할 수 없습니다.

뒤에 필수 위치 인수가 오지 않는 한, 물결표 문자(~)는 선택적 인수로 취급됩니다. 예를 들어, 다음 함수에서 물결표 문자(~)는 선택적 인수를 나타냅니다.

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)

무시된 입력값을 사용하여 함수를 호출하는 방법에 대한 자세한 내용은 함수 정의에서 입력값 무시하기 항목을 참조하십시오.

반복되는 인수

반복되는 인수는 인수로 반복하여 지정할 수 있는 위치 인수입니다. Repeating 특성을 포함하는 arguments 블록에 반복되는 인수를 선언하십시오.

arguments (Repeating)
    arg1
    arg2
    ...
end

함수는 입력값과 출력값에 대해 각각 하나의 Repeating arguments 블록을 가질 수 있습니다. Repeating input arguments 블록은 하나 이상의 반복되는 인수를 포함할 수 있는 반면, Repeating output arguments 블록은 반복되는 인수를 하나만 포함할 수 있습니다.

Repeating arguments 블록을 정의하는 함수는 블록에 있는 모든 인수를 전혀 사용하지 않거나 한 번 이상 사용하여 호출할 수 있습니다. 함수에 대한 호출에 반복되는 인수를 포함할 경우에는 반복될 때마다 Repeating arguments 블록의 모든 인수가 포함되어야 합니다.

예를 들어, Repeating arguments 블록이 입력 인수 x 및 y를 정의하는 경우에는 각 반복에 x와 y가 둘 다 포함되어야 합니다.

반복되는 입력 인수는 디폴트 값을 지정할 수 없으므로 선택 사항일 수 없습니다. 하지만 반복되는 어떤 인수도 포함하지 않고 함수를 호출할 수 있습니다.

함수는 위치 인수 뒤, 이름-값 인수 앞에 반복되는 입력 인수를 선언해야 합니다. Repeating 블록 내에는 이름-값 인수를 지정할 수 없습니다. 이름-값 인수에 대한 자세한 내용은 이름-값 인수 항목을 참조하십시오.

함수 내에서, 각각의 반복되는 인수는 함수 호출에 전달된 반복 횟수와 동일한 개수의 요소를 포함하는 셀형 배열이 됩니다. 유효성 검사는 셀형 배열의 각 요소에 적용됩니다. 이 인수를 사용하지 않고 함수를 호출하면 셀형 배열의 크기는 1×0이 됩니다. 다시 말해, 배열이 비어 있습니다.

예를 들어, 이 함수는 반복되는 인수 3개(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

입력값 없이 또는 입력값 3개의 배수를 사용하여 함수를 호출할 수 있습니다. MATLAB은 각 인수에 대해 해당 인수에 전달된 모든 값을 포함하는 셀형 배열을 만듭니다. fRepeat에 대한 다음 호출은 반복되는 인수 3개로 구성된 세트 2개를 전달합니다.

[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"]}

다음 함수는 Repeating arguments 블록의 x 입력값과 y 입력값에 대해 반복되는 인수를 받습니다. 반복되는 인수로 지정된 값은 함수 본문에서 셀형 배열 x와 y를 참조해 사용할 수 있습니다. 이 예제에서는 plot 함수에 대한 필수 입력값과 일치시키기 위해 x와 y의 값을 교대로 배치하고 있습니다(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을 사용하는 것은 권장하지 않습니다. repeating arguments 블록에서 varargin의 크기 또는 클래스가 제한될 경우 이 제한 사항은 varargin의 모든 값에 적용됩니다.

varargin을 사용하여 레거시 코드를 지원하는 경우, 이 인수는 Repeating arguments 블록에 있는 유일한 인수여야 합니다.

예를 들어, 다음 함수는 두 개의 필수 위치 인수와 함께 varargin을 반복되는 인수로 정의합니다.

function f(a, b, varargin)
    arguments
        a uint32
        b uint32
    end
    arguments (Repeating)
        varargin
    end
    
    % Function code
    ...
end

이름-값 인수

이름-값 인수는 함수에 전달되는 값에 이름을 연결합니다. 이름-값 인수의 특징은 다음과 같습니다.

• 어떤 순서로든 함수에 전달할 수 있습니다.

• 항상 선택적 인수입니다.

• 모든 위치 인수 및 반복되는 인수 뒤에 선언해야 합니다.

• Repeating 특성을 사용하는 arguments 블록에는 있을 수 없습니다.

• 여러 개의 이름-값 구조체를 사용할 때에도 고유한 이름을 사용해야 합니다.

• 위치 인수에 사용되는 이름은 사용할 수 없습니다.

점 표기법을 사용하여 구조체 필드를 정의하는 방법으로 arguments 블록에 이름-값 인수를 선언하십시오. 예를 들어, 구조체 NameValueArgs는 두 개의 이름-값 인수 Name1과 Name2를 정의합니다. 유효한 MATLAB 식별자이면 어떤 식별자이든 구조체 이름으로 사용할 수 있습니다.

arguments
    NameValueArgs.Name1
    NameValueArgs.Name2
end

구조체 이름은 함수 시그니처에 표시되어야 합니다.

function myFunction(NameValueArgs)

이름-값 구조체의 필드 이름을 사용하여 함수를 호출합니다.

myFunction(Name1=value1,Name2=value2)

R2021a 이전 릴리스에서는 이름을 string형 또는 문자형 벡터로 전달하고 이름과 값을 쉼표로 구분해야 합니다. 두 구문 모두 이후 릴리스에서 유효합니다.

함수 시그니처에 사용된 구조체 이름은 함수 작업 공간에 있는 구조체의 이름이며, 이 구조체는 함수에 전달된 이름과 값을 포함하고 있습니다.

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이 적용하는 버전은 지정된 마지막 버전입니다. 예를 들어, 다음과 같은 plot 호출을 실행하면 Color에 대한 값이 두 번 지정됩니다. MATLAB은 빨간색으로 플롯을 표시합니다.

plot(x,y,Color="blue",LineStyle="--",Color="red")

이름-값 인수의 디폴트 값

각 이름에 디폴트 값을 지정할 수 있습니다. 디폴트 값을 지정하지 않은 상태에서 이름-값 인수 없이 함수를 호출한 경우, 이름-값 구조체에 해당 필드가 없습니다. 이름-값 인수가 함수에 전달되지 않으면 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 이전 릴리스에서는 이름을 string형 또는 문자형 벡터로 전달하고 이름과 값을 쉼표로 구분해야 합니다. 예를 들면 다음과 같습니다.

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

반복되는 인수와 이름-값 인수 사용하기

함수가 반복되는 인수를 정의하면 repeating arguments 블록 다음에 오는 별도의 arguments 블록에 이름-값 인수를 선언해야 합니다. 예를 들어, 다음 함수는 두 개의 반복되는 인수 x와 y를 받습니다. x와 y의 모든 반복 항목을 지정한 후 PlotType 이름에 값 lin 또는 log를 할당하는 이름-값 인수를 지정할 수 있습니다.

함수 호출에 PlotType 인수가 포함되어 있는지 확인하려면 isfield 함수를 사용하여 scale 구조체에서 PlotType 필드를 확인하십시오.

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

R2021a 이전 릴리스에서는 이름을 string형 또는 문자형 벡터로 전달하고 이름과 값을 쉼표로 구분해야 합니다. 예를 들면 다음과 같습니다.

myLinLog(1:5,1:5,1:10,1:100:1000,"PlotType","log")

여러 개의 이름-값 구조체

함수 arguments 블록에는 여러 개의 이름-값 구조체가 포함될 수 있습니다. 하지만 필드 이름은 모든 구조체에서 고유해야 합니다. 이 함수에는 두 개의 이름-값 구조체 lineOptions와 fillOptions가 있습니다. 두 구조체는 동일한 필드 이름을 가질 수 없습니다.

myRectangle 함수의 인수는 다음과 같습니다.

• width와 height는 double형의 필수 위치 인수입니다.

• lineOptions.LineStyle은 디폴트 값 "-"를 가진 string형 스칼라입니다.

• lineOptions.LineWidth는 디폴트 값 1을 가진 숫자형 스칼라입니다.

• fillOptions.Color는 string형입니다.

• 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

이름-값 인수의 견고한 처리

함수에서 이름-값 인수를 구현하는 가장 좋은 방법은 arguments 블록에 정의하는 것입니다. arguments 블록을 사용하면 이름-값 인수를 구문 분석하기 위해 코드를 직접 작성할 필요가 없으며, "name",value 구문과 R2021a에 도입된 name=value 구문을 모두 구문 분석하는 견고한 인수를 구현할 수 있습니다.

유효한 이름 적용하기

arguments 블록에 이름-값 인수를 정의하면 이름이 유효한 식별자가 되도록 보장됩니다. 결과적으로 "name",value 구문 및 name=value 구문 모두에서 인수를 사용할 수 있습니다. 예를 들어, 유효하지 않은 식별자를 사용하는 이름-값 인수는 쉼표로 구분된 구문에서 사용할 수 있습니다.

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

그러나 allow-empty=true를 사용하는 동일한 호출은 오류를 발생시킵니다. arguments 블록에 이름-값 인수를 정의하면 정의된 이름이 유효한 MATLAB 변수 이름이고 name=value 구문과 호환 가능하도록 보장됩니다.

텍스트 입력값에서 예상치 않은 결과 방지하기

선택적 텍스트 입력값과 이름-값 인수를 모두 포함하는 함수의 경우 MATLAB이 텍스트 입력값을 이름-값 인수의 이름으로 해석할 위험이 있습니다. 다음 함수는 2개의 선택적 텍스트 입력값과 1개의 이름-값 인수를 포함합니다.

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

사용자가 다음 함수 호출을 입력하여 tag의 값을 "Mag"로, unit의 값을 "coulomb"로 설정하려고 합니다.

mySignal("Mag","coulomb")

그러나 MATLAB은 부분 일치를 통해 "Mag"를 이름-값 인수 Magnifer로 구문 분석합니다. "coulomb"는 해당 이름에 유효한 값이 아니므로 함수 오류가 발생합니다.

이를 방지하는 한 가지 방법은 디폴트 값을 제거하여 tag를 필수 인수로 만드는 것입니다.

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

MATLAB은 필수 입력값을 이름-값 인수로 구문 분석하지 않으므로 동일한 함수 호출이 이제는 tag의 값을 "Mag"로 설정하고 오류를 생성하지 않습니다.

또 다른 옵션은 3개 입력값을 모두 이름-값 인수로 설정하는 것입니다. 이렇게 하면 각 값이 이름에 연결되므로 입력값을 지정할 때 사용자가 실수하지 않도록 도와주며, 사용자가 입력값을 지정하는 순서는 최종 결과에 영향을 미치지 않습니다.

클래스 속성을 이름-값 인수로 사용하기

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 이전 릴리스에서는 이름을 string형 또는 문자형 벡터로 전달하고 이름과 값을 쉼표로 구분해야 합니다. 예를 들면 다음과 같습니다.

myBar(x,y,"FaceColor","magenta","BarLayout","grouped")

특정 속성 재정의하기

arguments 블록에서 특정 이름-값 인수를 가진 속성 이름을 다시 정의하여 클래스 속성 유효성 검사를 재정의할 수 있습니다.

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를 사용하여 함수를 호출합니다. bar 함수에서 지원하는 임의의 이름-값 쌍과 FaceColor의 값(red 또는 blue)을 선택적으로 전달합니다. FaceColor에는 다른 값이 허용되지 않습니다.

x = [1,2,3;4,5,6];
y = x.^2;
myBar(x,y)
myBar(x,y,FaceColor="red",BarLayout="grouped")

인수 유효성 검사 순서

함수가 호출되면 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은 a와 b를 uint32형으로 변환한 후 디폴트 값을 계산하고 c에 할당합니다. 이 경우, 두 입력값을 변환하면 값 2가 됩니다. 따라서 a와 b의 곱은 4입니다.

c =

  uint32

   4

세 번째 입력값에 값을 지정하면 함수는 c에 값을 할당하고 디폴트 값 표현식을 실행하지 않습니다.

c = f(1.8,1.5,25)

c =

  uint32

   25

클래스 및 크기 변환 방지하기

함수에 전달된 인수 값이 유효성 검사에서 요구하는 클래스 및 크기와 일치하지 않으면, MATLAB은 변환이 가능한 경우 이 값을 선언된 클래스와 크기로 변환합니다. MATLAB이 수행하는 표준 변환을 인수 유효성 검사에서 방지하려면 클래스 제한과 크기 제한 대신 유효성 검사 함수를 사용하십시오. 유효성 검사 함수에 대한 호출은 값을 반환하지 않으며 인수 값을 변경하지 않습니다.

예를 들어, 이 함수는 첫 번째 입력값을 double형 클래스의 임의 크기 2차원 배열로 제한합니다. 두 번째 입력값은 임의의 클래스로 구성된 5×3 배열이어야 합니다.

function f(a,b)
    arguments
        a (:,:) double
        b (5,3)
    end
    % Function code
end

표준 MATLAB 데이터형 변환 및 스칼라 확장 덕분에 다음 입력값을 사용하여 이 함수를 호출할 수 있으며, 이때 유효성 검사 오류는 발생하지 않습니다.

f('character vector',144)

기본적으로 MATLAB은 문자형 벡터의 요소를 상응하는 숫자형 값으로 변환하고 스칼라 확장을 적용하여 스칼라 값 144에서 5×3 배열을 만듭니다.

특화된 유효성 검사 함수를 사용하면 보다 구체적인 인수 유효성 검사가 가능합니다. 예를 들어, 이 함수는 첫 번째 인수와 두 번째 인수에 대한 클래스 사양과 크기 사양 대신 사용할 특화된 유효성 검사 함수를 정의합니다. 다음 로컬 함수를 사용하면 입력값이 변환되지 않도록 할 수 있습니다.

• 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 ',className,'.'];
        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 ',num2str(numDims),' dimension(s).'];
        throwAsCaller(MException(eid,msg))
    end
end

fCustomValidators를 사용하여 mustBeOfClass 함수를 호출합니다. 첫 번째 인수가 double형 클래스가 아니므로 함수는 오류를 반환합니다.

fCustomValidators('character vector',144)

Error using fCustomValidators
 fCustomValidators('character vector',144)
                   ↑
Invalid argument at position 1. Input must be of class double.

이 호출에서는 첫 번째 입력값의 차원 수가 올바르지 않으므로, 유효성 검사 함수가 사용자 지정 오류 메시지를 반환합니다.

fCustomValidators(ones(2,2,4),144)

Error using fCustomValidators
 fCustomValidators(ones(2,2,4),144)
                   ↑
Invalid argument at position 1. Input must have 2 dimension(s).

mustBeEqualSize 유효성 검사기 함수가 입력값의 크기가 같은지 확인합니다.

fCustomValidators(ones(2,2),144)

Error using fCustomValidators
 fCustomValidators(ones(2,2),144)
                             ↑
Invalid argument at position 2. Inputs must have equal size.

미리 정의된 관련 유효성 검사 함수는 mustBeA, mustBeFloat 및 mustBeVector를 참조하십시오.

인수 유효성 검사의 nargin

nargin 함수는 현재 실행 중인 함수 호출에 지정된 함수 입력 인수의 개수를 반환합니다. 함수 인수 유효성 검사를 사용할 때, 함수 내 nargin에서 반환하는 값은 함수가 호출될 때 제공된 위치 인수의 개수입니다.

반복되는 인수는 위치 인수이므로 호출 시 함수에 전달된 반복되는 인수의 개수는 nargin이 반환하는 값에 포함됩니다.

nargin이 반환하는 값에는 함수 호출에 없는 선택적 인수는 포함되지 않습니다. 또한 nargin은 어떤 이름-값 인수도 세지 않습니다.

nargin을 사용하여 호출 시 선택적 위치 인수가 함수에 전달되었는지 확인해 보십시오. 예를 들어, 이 함수는 3개의 위치 인수와 1개의 이름-값 인수를 선언합니다. 함수가 호출 시 전달된 인수를 확인하는 방법은 다음과 같습니다.

• nargin은 switch 블록을 사용하여 선택적 위치 인수 c가 함수에 전달되었는지 확인합니다.

• 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 블록에서 사용하지 마십시오.

assignin	builtin	clear
dbstack	eval	evalc
evalin	exist	feval
input	inputname	load
nargin	narginchk	nargoutchk
save	whos	who

이 제한 사항은 arguments 블록 내에만 적용되고 함수 본문의 변수 또는 함수에는 적용되지 않습니다.

arguments 블록 디버그하기

arguments 블록 내부를 디버그할 때 작업 공간은 읽기 전용입니다. 즉, 작업 공간을 검사하고 변수에 할당된 값을 확인할 수 있습니다. 그러나 작업 공간이 읽기 전용 상태인 동안 새로운 변수를 만들거나 기존 변수에 할당된 값을 변경할 수는 없습니다. 디버거가 arguments 블록 외부로 이동하면 다시 변수를 만들거나 편집할 수 있게 됩니다.

참고 항목

namedargs2cell | arguments

관련 항목

• 인수 정의
• 인수 유효성 검사 함수
• 속성값 유효성 검사