addParameter

Add optional name-value pair argument into input parser scheme

collapse all in page

Syntax

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

Description

example

addParameter(p,paramName,defaultVal) adds the parameter name of an optional name-value pair argument into the input parser scheme. When the inputs to a function do not include this optional name-value pair, the input parser assigns paramName the value defaultVal.

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

example

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

addParameter(___,'PartialMatchPriority',matchPriorityValue) specifies the priority for the partial matching of conflicting parameter names. The input parser scheme selects lower priority values over higher ones. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

collapse all

Open Live Script

Create an inputParser object and add a name-value pair into the input scheme.

p = inputParser;
paramName = 'myParam';
defaultVal = 0;
addParameter(p,paramName,defaultVal)

Pass both the parameter name and value to the parse method, and display the results.

parse(p,'myParam',100);
p.Results
ans = struct with fields:
    myParam: 100

Validate that the value corresponding to myParam, with a default value of 1, is a numeric scalar greater than zero.

Create an input parser scheme. For the validation function, @(x) creates a handle to an anonymous function that accepts one input.

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

Parse an invalid input argument, such as -1.

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

Define a validation function using validateattributes. Validate that an argument is a nonempty character vector.

validationFcn = @(x) validateattributes(x,{'char'},{'nonempty'});

Create an input parser scheme that includes an optional name-value pair argument, with a parameter name myName and a default value of 'John Doe'. Validate the input argument with validationFcn.

p = inputParser;
paramName = 'myName';
defaultVal = 'John Doe';
addParameter(p,paramName,defaultVal,validationFcn)

Define myName as a number. The 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 character vector. The parse passes.

parse(p,'myName','George')

Input Arguments

collapse all

Input parser scheme, specified as an inputParser object.

Name of the input parameter, specified as a character vector or string scalar.

Example: "firstName"

Example: 'address'

Data Types: char | string

Default value for the input, specified as any data type. If argName is not an input to the function, when the parse function parses the inputs, then it assigns argName the value defaultVal.

Function to validate an argument, specified as a function handle.

The function handle must be associated with a function that returns true or false, or passes a test, or throws an error. Both types of functions must accept a single input argument.

Example: @(s)isstring(s)

Example: @(x)isnumeric(x)&&isscalar(x)

Example: @(n)validateattributes(n,{'numeric'},{'nonnegative'})

Data Types: function_handle

Priority for partial matching of conflicting parameter names, specified as a positive integer. The input parser scheme selects lower priority values over higher ones. If partial parameter names are ambiguous and have the same priority, then parse throws an error. If the names are ambiguous, but have different priority values, then parse issues a warning that indicates the matched name.

Tips

  • Parameter name-value pairs are optional inputs. When calling the function, name-value pairs can appear in any order after positional arguments. They take the general form Name1,Value1,...,NameN,ValueN.

See Also

| | |

Topics

Introduced in R2013b

MATLAB Documentation

Support