addOptional

Add optional, positional argument into input parser scheme

collapse all in page

Syntax

addOptional(p,argName,defaultVal)
addOptional(p,argName,defaultVal,validationFcn)

Description

addOptional(p,argName,defaultVal) adds an optional, positional input argument, argName, into the input parser scheme p. When the inputs to a function do not include a value for this optional input, the input parser assigns it the value defaultVal.

example

addOptional(p,argName,defaultVal,validationFcn) specifies a validation function for the input argument.

example

Examples

collapse all

Open Live Script

Create an inputParser object and add an optional input to the input parser scheme. Name the argument myinput, and assign it a default value of 13.

p = inputParser;
argName = 'myInput';
defaultVal = 13;
addOptional(p,argName,defaultVal)

Call the parse function with no inputs, and display the results.

parse(p)
p.Results
ans = struct with fields:
    myInput: 13

Call the parse function with an input value of 42, and display the results.

parse(p,42)
p.Results
ans = struct with fields:
    myInput: 42

Validate that an optional input named num, 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;
argName = 'num';
defaultVal = 1;
validationFcn = @(x) isnumeric(x) && isscalar(x) && (x > 0);
addOptional(p,argName,defaultVal,validationFcn)

Parse an invalid input argument, such as -1.

parse(p,-1)
The value of 'num' is invalid. It must satisfy the function: @(x)isnumeric(x)&&isscalar(x)&&(x>0).

Define a validation function using validateattributes. Validate that an argument is numeric, positive, and even.

validationFcn = @(x) validateattributes(x,{'numeric'},...
    {'even','positive'});

Create an input parser scheme that includes an optional evenPosNum argument with a default value of 1. Validate the input argument with validationFcn.

p = inputParser;
argName = 'evenPosNum';
defaultVal = 1;
addOptional(p,argName,defaultVal,validationFcn)

Parse an input string. Parse fails.

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

numeric

Instead its type was string.

Parse an odd number. Parse fails.

 parse(p,13)
The value of 'evenPosNum' is invalid. Expected input to be even.

Parse an even, positive number. Parse passes.

parse(p,42)

Input Arguments

collapse all

Input parser scheme, specified as an inputParser object.

Name of the input argument, 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

Tips

  • Arguments added to the input parser scheme with the addOptional function are positional. Therefore, add them to the input parser scheme in the same order they are passed into the function.

  • For optional string arguments, specify a validation function. Without a validation function, the input parser interprets a string argument as an invalid parameter name and throws an error.

  • Use addOptional to add an individual argument into the input parser scheme. If you want to parse an optional name-value pair, then use the addParameter function.

Version History

Introduced in R2007a

See Also

| | |

Topics