関数入力の解析
この例では、必須の入力とオプションの入力を定義して、入力パーサーを使ってオプションの入力に既定値を代入し、カスタム関数へのすべての入力を検証する方法を示します。
入力パーサーは入力を検証して既定値を代入する一貫した方法を提供し、コードのロバスト性と管理性を向上させます。入力を検証するには既存の MATLAB® 関数を利用するか、独自の検証ルーチンを記述することができます。
手順 1.関数を定義する。
printPhoto.m
というファイルに関数を作成します。関数 printPhoto
ではファイル名が必須入力ですが、オプションとして仕上げ (光沢またはつや消し)、色空間 (RGB または CMYK)、幅および高さを入力できます。
function printPhoto(filename,varargin)
関数宣言ステートメントで、まず必須の入力を指定します。オプションの入力をサポートするには varargin
を使用します。
手順 2.inputParser オブジェクトを作成する。
関数内で inputParser
を呼び出してパーサー オブジェクトを作成します。
p = inputParser;
手順 3.スキームに入力を追加する。
addRequired
、addOptional
または addParameter
を使用して、関数内の解析スキームに入力を追加します。オプションの入力には既定値を指定します。
各入力に対し、入力をチェックしてスカラー論理値 (true
か false
) またはエラーを返す、検証関数へのハンドルを指定することができます。検証関数には、既存の MATLAB 関数 (ischar
や isnumeric
など) または独自に作成した関数 (無名関数やローカル関数など) を使用できます。
関数 printPhoto
において filename
は必須の入力です。finish
と color
をオプションの入力として定義し、width
と height
をオプションのパラメーター値のペアとして定義します。
defaultFinish = 'glossy'; validFinishes = {'glossy','matte'}; checkFinish = @(x) any(validatestring(x,validFinishes)); defaultColor = 'RGB'; validColors = {'RGB','CMYK'}; checkColor = @(x) any(validatestring(x,validColors)); defaultWidth = 6; defaultHeight = 4; addRequired(p,'filename',@ischar); addOptional(p,'finish',defaultFinish,checkFinish) addOptional(p,'color',defaultColor,checkColor) addParameter(p,'width',defaultWidth,@isnumeric) addParameter(p,'height',defaultHeight,@isnumeric)
addRequired
または addOptional
で追加する入力は、"位置" 引数です。位置入力を指定して関数を呼び出す際は、解析スキームに追加される順序に従ってこれらの値を指定します。
addParameter
で追加される入力は位置引数ではないため、height
の値を渡すのは width
の前後いずれでも構いません。ただし、パラメーター値の入力の場合、入力の値と共にその名前 (height
または width
) を渡す必要があります。
関数がオプションの入力 string または文字ベクトルと、名前と値の引数を受け入れる場合、オプションの入力用に検証関数を指定します。これを行わないと、入力パーサーでオプションの string または文字ベクトルがパラメーター名として解釈されます。たとえば、検証関数 checkFinish
では、printPhoto
によって 'glossy'
が無効なパラメーター名ではなく finish
の値として解釈されるようにします。
手順 4.解析を調整するプロパティを設定する (オプション)。
既定の設定で入力パーサーは、大文字と小文字の区別、関数名、構造体配列入力およびスキームにない追加のパラメーター名と値を許可するかどうかについての仮定を実行します。プロパティを使用すると、こうした動作を明示的に定義することができます。プロパティはドット表記を使って設定しますが、これは構造体配列に値を代入する方法と似ています。
printPhoto
によって入力スキームに一致しない追加パラメーター値の入力が受け入れられように、入力パーサーの KeepUnmatched
プロパティを設定します。
p.KeepUnmatched = true;
KeepUnmatched
が false
(既定の設定) の場合、入力がスキームに一致しないと入力パーサーでエラーが発生します。
手順 5.入力を解析する。
関数内で parse
メソッドを呼び出します。関数のすべての入力の値を渡します。
parse(p,filename,varargin{:})
手順 6.関数で入力を使用する。
解析後の入力にアクセスするには inputParser
オブジェクトの以下のプロパティを使用します。
Results
— スキームにあるすべての入力の名前と値が格納された構造体配列Unmatched
— 関数に渡された、スキームに含まれていないパラメーターの名前と値が格納された構造体配列 (KeepUnmatched
がtrue
の場合)UsingDefaults
— 関数に渡されなかったため既定の値が代入されたオプション入力の名前が格納された cell 配列
関数 printPhoto
内で、一部の入力の値を表示します。
disp(['File name: ',p.Results.filename]) disp(['Finish: ', p.Results.finish]) if ~isempty(fieldnames(p.Unmatched)) disp('Extra inputs:') disp(p.Unmatched) end if ~isempty(p.UsingDefaults) disp('Using defaults: ') disp(p.UsingDefaults) end
手順 7.関数を呼び出す。
入力パーサーでは、各入力を次のように受け取ることを予期しています。
まず、必須の入力を、
addRequired
で解析スキームに追加された順序で受け取る。オプションの位置入力を、
addOptional
で解析スキームに追加された順序で受け取る。位置入力を、パラメーターの名前と値のペア入力の前に受け取る。
パラメーターの名前と値を
Name1,Value1,...,NameN,ValueN
の形式で受け取る。
有効なものと無効なものを含めて、入力の組み合わせをいくつか printPhoto
に渡します。
printPhoto('myfile.jpg')
File name: myfile.jpg Finish: glossy Using defaults: 'finish' 'color' 'width' 'height'
printPhoto(100)
Error using printPhoto (line 23) The value of 'filename' is invalid. It must satisfy the function: ischar.
printPhoto('myfile.jpg','satin')
Error using printPhoto (line 23) The value of 'finish' is invalid. Expected input to match one of these strings: 'glossy', 'matte' The input, 'satin', did not match any of the valid strings.
printPhoto('myfile.jpg',height=10,width=8)
File name: myfile.jpg Finish: glossy Using defaults: 'finish' 'color'
R2021a より前のバージョンで名前と値の引数を使用する場合、string または文字ベクトルとして名前を渡し、名前と値をコンマで区切ります。以下に例を示します。
printPhoto('myfile.jpg','height',10,'width',8)
n 番目の位置入力の値を渡すには、その前 (n – 1) の入力の値を指定するか、入力をパラメーター名と値のペアとして渡します。たとえば、以下の関数呼び出しでは finish
(既定値 'glossy'
) と color
に同じ値が代入されます。
printPhoto('myfile.gif','glossy','CMYK') % positional printPhoto('myfile.gif',color='CMYK') % name and value