Main Content

이름-값 인수의 유효성 검사하기

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

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

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

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

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

참고 항목

|

관련 항목