addParameter

Class: inputParser

Add optional parameter name-value pair argument to input parser scheme

Syntax

addParameter(p,paramName,default)
addParameter(p,paramName,default,validationFcn)
addParameter(___,'PartialMatchPriority', matchPriorityValue)

Description

addParameter(p,paramName,default) adds parameter name and value argument paramName to the input parser scheme of inputParser object, p. When the inputs that you are checking do not include a value for this optional parameter, the input parser assigns the default value.

addParameter(p,paramName,default,validationFcn) specifies a validation function for the input argument.

addParameter(___,'PartialMatchPriority', matchPriorityValue) allows specification of matchPriorityValue to indicate priority for matching of conflicting partial parameter names and can include any of the input arguments in the previous syntaxes.

Input Arguments

p

Object of class inputParser.

paramName

String that specifies the internal name for the input parameter.

Parameter names and values are optional inputs. When calling the function, name and value pairs can appear in any order, with the general form Name1,Value1,...,NameN,ValueN.

default

Default value for the input. This value can be of any data type.

matchPriorityValue

Positive integer value indicating the priority for matching of conflicting partial parameter names. The input parser selects lower priority values over higher ones. If, within an input parser scheme, partial parameter names are ambiguous and have the same priority, inputParser will throw an error. If the names are ambiguous, but have different PartialMatchPriority values, inputParser issues a warning indicating the matched name.

Default: 1

validationFcn

Handle to a function that checks if the input argument is valid.

inputParser accepts two types of validation functions: functions that return true or false, and functions that pass or throw an error. Both types of validation functions must accept a single input argument.

Examples

expand all

Add Optional Parameter Value Input

Create an inputParser object and add an optional input named myparam with a default value of 0 to the input scheme.

p = inputParser;
paramName = 'myparam';
default = 0;
addParameter(p,paramName,default);

Unlike the positional inputs added with the addRequired and addOptional methods, each parameter added with addParameter corresponds to two input arguments: one for the name and one for the value of the parameter.

Pass both the parameter name and value to the parse method.

parse(p,'myparam',100);
p.Results
ans = 

    myparam: 100

Validate Parameter Value

Check whether the value corresponding to myparam is a numeric scalar greater than zero.

p = inputParser;
paramName = 'myparam';
default = 1;
errorStr = 'Value must be positive, scalar, and numeric.'; 
validationFcn = @(x) assert(isnumeric(x) && isscalar(x) ...
    && (x > 0),errorStr);
addParameter(p,paramName,default,validationFcn)

The syntax @(x) creates a handle to an anonymous function with one input.

Attempt to parse an invalid value, such as -1:

parse(p,'myparam',-1)
The value of 'myparam' is invalid. Value must be positive, scalar, and numeric.

Validate Parameter Value Input with validateattributes

Create an inputParser object and define a validation function using validateattributes to test that input parameter myName is a nonempty string.

p = inputParser;
paramName = 'myName';
default = 'John Doe';
validationFcn = @(x) validateattributes(x,{'char'},{'nonempty'}); 
addParameter(p,paramName,default,validationFcn)

Define myName as a number. The attempt to parse fails.

parse(p,'myName',1138)
The value of 'myName' is invalid. Expected input to be one of these types:

char

Instead its type was double.

Parse a string. The attempt to parse passes.

parse(p,'myName','George')
Was this topic helpful?