Quantcast

Documentation Center

  • Trial Software
  • Product Updates

addOptional

Class: inputParser

Add optional positional argument to input parser scheme

Syntax

addOptional(p,argName,default)
addOptional(p,argName,default,validationFcn)

Description

addOptional(p,argName,default) adds optional input, argName, to the input parser scheme of inputParser object, p. When the inputs that you are checking do not include a value for this optional input, the input parser assigns the default value to the input.

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

Tips

  • For optional string inputs, specify a validation function. Without a validation function, the input parser interprets valid string inputs as invalid parameter names 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, use addParameter.

Input Arguments

p

Object of class inputParser.

argName

String that specifies the internal name for the input argument.

Arguments added with addOptional are positional. When you call a function with positional inputs:

  • Specify inputs in the same order that they are added into the input parser scheme.

  • Specify a value for the kth argument by assigning values for the first (k–1) arguments in the input scheme.

default

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

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 Input

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

p = inputParser;
argName = 'myinput';
default = 0;
addOptional(p,argName,default);

Validate Optional Input

Check whether an optional input named num with a default value of 1 is a numeric scalar greater than zero.

p = inputParser;
argName = 'num';
default = 1;
validationFcn = @(x) isnumeric(x) && isscalar(x) && (x > 0);
addOptional(p,argName,default,validationFcn);

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

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

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

Validate Optional Input with validateattributes

Create an inputParser object and define a validation function using validateattributes to test that optional input is numeric, positive, and even. Add the required input to the scheme.

p = inputParser;
argName = 'evenPosNum';
default = 1;
validationFcn = @(x) validateattributes(x,{'numeric'},...
    {'even','positive'}); 
addOptional(p,argName,default,validationFcn);

Parse an input string. Parse will fail.

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

double, single, uint8, uint16, uint32, uint64, int8, int16, int32, int64

Instead its type was char.

Parse an odd number. Parse will fail.

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

Parse an even, positive number. Parse will pass.

parse(p,42)

See Also

| | | |

More About

Was this topic helpful?