addParameter - Add optional name-value pair argument into input parser scheme - MATLAB (original) (raw)
Add optional name-value pair argument into input parser scheme
Syntax
Description
addParameter([p](#d126e895908),[paramName](#d126e895930),[defaultVal](#btwhc7r-1%5Fsep%5Fshared-default)) 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 valuedefaultVal.
Unlike positional inputs added with the addRequired andaddOptional functions, each parameter added withaddParameter corresponds to two input arguments: one for the name and one for the value.
addParameter([p](#d126e895908),[paramName](#d126e895930),[defaultVal](#btwhc7r-1%5Fsep%5Fshared-default),[validationFcn](#btwhc7r-1%5Fsep%5Fshared-validationFcn)) specifies a validation function for the input argument.
addParameter(___,'PartialMatchPriority',[matchPriorityValue](#d126e896026)) 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
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 tomyParam, 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.
The value of 'myparam' is invalid. Value must be positive, scalar, and numeric.
Define a validation function usingvalidateattributes. 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 withvalidationFcn.
p = inputParser; paramName = 'myName'; defaultVal = 'John Doe'; addParameter(p,paramName,defaultVal,validationFcn)
Define myName as a number. The parse fails.
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
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.
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, thenparse 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.
Version History
Introduced in R2013b