inputParser

関数の入力パーサー

説明

inputParser オブジェクトを使用すると、入力パーサースキームを作成して関数の入力を管理できます。入力をチェックするには、必須の引数、オプションの引数および名前と値のペアの引数の検証関数を定義できます。オプションとして、大文字小文字の区別、構造体配列入力および入力パーサースキームにない入力など、解析動作を調整するプロパティを設定できます。

入力パーサースキームを定義した後に、関数 parse を呼び出します。inputParser は入力に関する情報を格納します。

入力の名前と値	格納場所
入力パーサースキームに一致する	`Results` プロパティ
関数に渡されないため、既定値が割り当てられる	`UsingDefaults` プロパティ
入力パーサースキームに一致しない	`Unmatched` プロパティ

作成

構文

p = inputParser

説明

p = inputParser は既定のプロパティ値をもつ入力パーサーオブジェクトを作成します。

例

プロパティ

すべて展開する

`CaseSensitive` — 大文字小文字を区別するかどうかのインジケーター
`false` (既定値) | `true`

引数名のチェック時に大文字小文字を区別するかどうかのインジケーター。false または true (あるいは 0 または 1) として指定します。既定では、引数名の一致に関して大文字小文字は区別されません。たとえば、'a' は 'A' と一致します。一致で大文字と小文字を区別するには、CaseSensitive を true (または 1) に設定します。

このプロパティ値は logical 値として格納されます。

`FunctionName` — エラーメッセージの関数名
空の文字ベクトル `''` (既定値) | 文字ベクトル | string スカラー

エラーメッセージに表示する関数名。文字ベクトルまたは string スカラーとして指定します。既定では、FunctionName は空の文字ベクトル ('') です。通常、FunctionName を検証している関数の名前に設定します。これにより、関数 parse が無効な入力引数を検出した場合、その関数名を使用してエラーをレポートします。

このプロパティ値は文字ベクトルとして格納されます。

データ型: char | string

`KeepUnmatched` — 一致インジケーター
`false` (既定値) | `true`

入力パーサースキームで入力が検出されない場合にエラーをスローする一致インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、関数 parse は、入力引数名が入力パーサースキームで定義されたものと一致しない場合にエラーをスローします。このエラーを非表示にして、入力引数の名前と値を格納するには、KeepUnmatched を true (または 1) に設定します。inputParser は一致しなかった入力引数の名前と値を Unmatched プロパティに格納します。

このプロパティ値は logical 値として格納されます。

`PartialMatching` — 部分一致インジケーター
`true` (既定値) | `false`

部分的に一致した入力名を有効として受け入れる部分一致インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、入力パーサースキーム内のパラメーター名の冒頭の部分文字列である入力パラメーター名は有効であり、入力値はそのパラメーターと一致します。入力パラメーターに一致する候補が複数存在する場合、MATLAB^® はエラーをスローします。入力パラメーター名が、CaseSensitive プロパティに従って入力パーサースキーム内の名前に完全一致する必要がある場合は、PartialMatching を false (または 0) に設定します。

部分一致は、関数 addParameter を使用して入力パーサースキームに追加する引数でのみサポートされます。

StructExpand プロパティの値が true (または 1) の場合、inputParser は入力パラメーター名に対応する構造体フィールド名について部分一致をサポートしていません。
PartialMatching と KeepUnmatched の両方が true (または 1) の場合、MATLAB はエラーをスローしません。代わりに、あいまいなパラメーター名を Unmatched プロパティに格納します。

このプロパティ値は logical 値として格納されます。

`StructExpand` — 構造体インジケーター
`true` (既定値) | `false`

構造体を単一の入力、または一連のパラメーターの名前と値のペアとして解釈する構造体インジケーター。false または true (あるいは 0 または 1) として指定します。既定では、inputParser は構造体を個別の入力に展開します。各フィールド名は入力パラメーター名に対応します。構造体を単一の入力引数と見なすには、StructExpand を false (または 0) として指定します。

このプロパティ値は logical 値として格納されます。

`Parameters` — 引数名
読み取り専用: 文字ベクトルの cell 配列

このプロパティは読み取り専用です。

入力パーサースキームで定義される引数名。文字ベクトルの cell 配列として格納されます。スキームに入力引数を追加する各関数は、Parameters プロパティを更新します。このような関数には addRequired、addOptional、および addParameter があります。

データ型: cell

`Results` — 結果
読み取り専用: 構造体

このプロパティは読み取り専用です。

有効な入力引数の名前、および対応する値として指定される結果。構造体として格納されます。有効な入力引数は、入力パーサースキームで定義された引数に一致する名前をもつものです。Results 構造体の各フィールドは、入力パーサースキーム内の引数の名前に対応します。関数 parse によって Results プロパティが入力されます。

データ型: struct

`Unmatched` — 不一致の入力
読み取り専用: 構造体

このプロパティは読み取り専用です。

入力パーサースキームに一致しない、不一致の入力の名前と値。構造体として格納されます。KeepUnmatched プロパティが false (または 0) に設定されている場合 (既定)、またはすべての入力が入力パーサースキームに一致した場合、Unmatched はフィールドのない 1 行 1 列の構造体になります。それ以外の場合、Unmatched 構造体の各フィールドは、入力パーサースキームで定義された引数に一致しない入力引数の名前に対応します。

関数 parse によって Unmatched プロパティが入力されます。

データ型: struct

`UsingDefaults` — 関数に明示的に渡されない入力
読み取り専用: 文字ベクトルの cell 配列

このプロパティは読み取り専用です。

関数に明示的に渡されない入力。文字ベクトルの cell 配列として格納されます。これらの入力引数には、Results プロパティの既定値が割り当てられます。関数 parse によって UsingDefaults プロパティが入力されます。

データ型: cell

オブジェクト関数

`addOptional`	入力パーサースキームにオプションの位置引数を追加
`addParameter`	オプションの名前と値のペア引数を入力パーサースキームに追加
`addRequired`	入力パーサースキームに必須の位置引数を追加
`parse`	関数入力の解析
`addParamValue`	(非推奨) オプションの名前と値のペア引数を入力パーサースキームに追加

入力パーサースキームは、関数 addRequired、addOptional、addParameter を任意の順序で呼び出すことで定義できます。ただし、入力パーサーを使用する関数を呼び出した場合、引数は次の順序で渡されます。

必須の引数
任意のオプションの位置引数
名前と値のペア

例

すべて折りたたむ

入力の検証

必須およびオプションの引数の妥当性をチェックします。

関数をファイル findArea.m に作成します。関数 findArea には入力引数 width が必須で、可変数の追加入力を受け入れます。入力パーサースキームは、次の引数の条件を指定します。

width (必須の引数)。必須の引数は位置引数であるため、width は関数 findArea の最初の引数でなければなりません。入力パーサーは、width が正の数値スカラーであるかをチェックします。
height (オプション引数)。オプション引数は位置引数であるため、height が関数 findArea の引数である場合、2 番目の引数でなければなりません。入力パーサーは、height が正の数値スカラーであるかをチェックします。
'units' および関連付けられた値 (名前と値のペア)。名前と値のペアはオプションです。関数 findArea を呼び出すときに、位置引数の後に名前と値のペアを任意の順序で指定します。入力パーサーは、'units' の値が string であるかをチェックします。
'shape' および関連付けられた値 (別の名前と値のペア)。入力パーサーは、'shape' の値が配列 expectedShapes に含まれているかをチェックします。

function a = findArea(width,varargin)
   defaultHeight = 1;
   defaultUnits = 'inches';
   defaultShape = 'rectangle';
   expectedShapes = {'square','rectangle','parallelogram'};

   p = inputParser;
   validScalarPosNum = @(x) isnumeric(x) && isscalar(x) && (x > 0);
   addRequired(p,'width',validScalarPosNum);
   addOptional(p,'height',defaultHeight,validScalarPosNum);
   addParameter(p,'units',defaultUnits,@isstring);
   addParameter(p,'shape',defaultShape,...
                 @(x) any(validatestring(x,expectedShapes)));
   parse(p,width,varargin{:});
   
   a = p.Results.width*p.Results.height; 
end

関数 findArea を複数回呼び出します。入力パーサーは、これらの関数呼び出しのいずれでもエラーをスローしません。

a = findArea(7);
a = findArea(7,3);
a = findArea(13,'shape','square');
a = findArea(13,'units',"miles",'shape','square');

入力パーサースキームに一致しない引数を指定して関数を呼び出します。width 入力に数値以外の値を指定します。

a = findArea('text')

Error using findArea (line 14)
The value of 'width' is invalid. It must satisfy the function: @(x)isnumeric(x)&&isscalar(x)&&(x>0).

'shape' にサポートされていない値を指定します。

a = findArea(4,12,'shape','circle')

Error using findArea (line 14)
The value of 'shape' is invalid. Expected input to match one of these values:

'square', 'rectangle', 'parallelogram'

The input, 'circle', did not match any of the valid values.

追加のパラメーター値入力

ライブスクリプトを開く

エラーを発生させる代わりに、入力スキームにはないパラメーター名と値入力を保存します。

default = 0;
value = 1;

p = inputParser;
p.KeepUnmatched = true;
addOptional(p,'expectedInputName',default)
parse(p,'extraInput',value);

次のように不一致のパラメーター名と値を表示します。

p.Unmatched

ans = struct with fields:
    extraInput: 1

大文字小文字の区別

関数の入力をチェックするときに大文字小文字を区別します。

p = inputParser;
p.CaseSensitive = true;
defaultValue = 0;
addParameter(p,'InputName',defaultValue)

parse(p,'inputname',10)

'inputname' is not a recognized parameter. For a list of valid name-value pair arguments, see the documentation for this function.

構造体配列の入力。

ライブスクリプトを開く

構造体引数を名前と値のペアに展開します。

s.input1 = 10;
s.input2 = 20;
default = 0;

p = inputParser;
addParameter(p,'input1',default)
addParameter(p,'input2',default)
parse(p,s)

p.Results

ans = struct with fields:
    input1: 10
    input2: 20

StructExpand プロパティを false に設定することで、構造体を単一の引数として受け入れます。

s2.first = 1;
s2.random = rand(3,4,2);
s2.mytext = 'some text';

p = inputParser;
p.StructExpand = false;
addRequired(p,'structInput')
parse(p,s2)

results = p.Results

results = struct with fields:
    structInput: [1×1 struct]

fieldList = fieldnames(p.Results.structInput)

fieldList = 3×1 cell
    {'first' }
    {'random'}
    {'mytext'}

`validateattributes` を使用した入力の解析

ユーザーに関する情報を解析し、解析がパスした場合に、その情報を cell 配列に追加する関数を作成します。

関数 addPerson を作成し、関数 validateattributes を使用する入力パーサースキームを含めます。関数 addPerson はユーザーのリストを受け入れ、必要に応じてこのリストを変更し、その後リストを返します。関数を呼び出すたびに新規オブジェクトが作成されることを防ぐために、永続的な inputParser オブジェクトを使用します。

function mlist = addPerson(mlist,varargin)
    persistent p
    if isempty(p)
        p = inputParser;
        p.FunctionName = 'addPerson';
        addRequired(p,'name',@(x)validateattributes(x,{'char'},...
            {'nonempty'}))
        addRequired(p,'id',@(x)validateattributes(x,{'numeric'},...
            {'nonempty','integer','positive'}))
        addOptional(p,'birthyear',9999,@(x)validateattributes(x,...
            {'numeric'},{'nonempty'}))
        addParameter(p,'nickname','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
        addParameter(p,'favColor','-',@(x)validateattributes(x,...
            {'char'},{'nonempty'}))
    end
    
    parse(p,varargin{:})
    
    if isempty(mlist)
        mlist = fieldnames(p.Results)';
    end
    mlist = [mlist; struct2cell(p.Results)'];
end

空のリストを作成し、そのリストにユーザーを追加します。

pList = {};
pList = addPerson(pList,78,'Joe');

Error using addPerson
The value of 'name' is invalid. Expected input to be one of these types:

char

Instead its type was double.

Error in addPerson (line 19)
parse(p,varargin{:})

解析は失敗します。これは、関数が引数を正しくない順序で受け取り、name に値 78 を代入しようとするためです。このエントリは pList に追加されません。

さらに数名のユーザーをリストに追加します。

pList = addPerson(pList,'Joe',78);
pList = addPerson(pList,'Mary',3,1942,'favColor','red');
pList = addPerson(pList,'James',182,1970,'nickname','Jimmy')

pList =

  4×5 cell array

    'birthyear'    'favColor'    'id'     'name'     'nickname'
    [     9999]    '-'           [ 78]    'Joe'      '-'       
    [     1942]    'red'         [  3]    'Mary'     '-'       
    [     1970]    '-'           [182]    'James'    'Jimmy'

ヒント

関数 addOptional で入力パーサースキームに追加された引数は位置引数です。このため、関数に渡されるときと同じ順序でこれらを入力パーサースキームに追加します。
入力パーサースキームに個々の引数を追加するには、addOptional を使用します。オプションの名前と値のペアを解析する場合は、関数 addParameter を使用します。

拡張機能

すべて展開する

スレッドベースの環境
MATLAB® の `backgroundPool` を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の `ThreadPool` を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2007a で導入

参考

validateattributes | validatestring | varargin | arguments

inputParser

説明

作成

構文

説明

プロパティ

CaseSensitive — 大文字小文字を区別するかどうかのインジケーター false (既定値) | true

FunctionName — エラー メッセージの関数名 空の文字ベクトル '' (既定値) | 文字ベクトル | string スカラー

KeepUnmatched — 一致インジケーター false (既定値) | true

PartialMatching — 部分一致インジケーター true (既定値) | false

StructExpand — 構造体インジケーター true (既定値) | false

Parameters — 引数名 読み取り専用: 文字ベクトルの cell 配列

Results — 結果 読み取り専用: 構造体

Unmatched — 不一致の入力 読み取り専用: 構造体

UsingDefaults — 関数に明示的に渡されない入力 読み取り専用: 文字ベクトルの cell 配列

オブジェクト関数

例

入力の検証

追加のパラメーター値入力

大文字小文字の区別

構造体配列の入力。

validateattributes を使用した入力の解析

ヒント

拡張機能

スレッドベースの環境 MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

バージョン履歴

参考

トピック

`CaseSensitive` — 大文字小文字を区別するかどうかのインジケーター
`false` (既定値) | `true`

`FunctionName` — エラーメッセージの関数名
空の文字ベクトル `''` (既定値) | 文字ベクトル | string スカラー

`KeepUnmatched` — 一致インジケーター
`false` (既定値) | `true`

`PartialMatching` — 部分一致インジケーター
`true` (既定値) | `false`

`StructExpand` — 構造体インジケーター
`true` (既定値) | `false`

`Parameters` — 引数名
読み取り専用: 文字ベクトルの cell 配列

`Results` — 結果
読み取り専用: 構造体

`Unmatched` — 不一致の入力
読み取り専用: 構造体

`UsingDefaults` — 関数に明示的に渡されない入力
読み取り専用: 文字ベクトルの cell 配列

`validateattributes` を使用した入力の解析

スレッドベースの環境
MATLAB® の `backgroundPool` を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の `ThreadPool` を使用してコードを高速化します。