Learn more about MATLAB

addOptional (inputParser) - Add optional argument to Input Parser scheme

Syntax

p.addOptional(argname, default, validator)
addParamValue(p, argname, default, validator)

Description

p.addOptional(argname, default, validator) is part of the input argument checking mechanism employed by the MATLAB Input Parser utility. Input Parser code residing in a function that receives data from calling functions identifies what types of arguments are acceptable. The addOptional function identifies those arguments that are optional, and are not expressed in parameter name/value format.

Input value p is an object of the inputParser class that creates an input scheme to identify all valid arguments one might pass to the function.

The string argname contains the internal name given to this argument. Specify this name in a string enclosed within single quotation marks.

The default input specifies the value to use whenever this optional argument is not passed by the calling function.

The optional validator is a handle to a function that is to be used by the Input Parser to validate input data passed by the caller. If the validator function returns false or errors, the parsing fails and MATLAB throws an error.

addParamValue(p, argname, default, validator) is functionally the same as the syntax above.

For more information on the inputParser class, see Validating Inputs with Input Parser in the MATLAB Programming Fundamentals documentation.

Example

This example writes a function called photoPrint that uses the Input Parser to check arguments passed to it. This function accepts up to eight input arguments. When called with the full set of inputs, the syntax is:

photoPrint(filename, format, finish, colorCode, ...
   'horizDim', hDim, 'vertDim', vDim);

Only the first two of these inputs are defined as required arguments; the rest are optional. The 'horizDim' and 'vertDim' arguments are in parameter name/value format. Pair the 'horizDim' parameter name with its value hDim, and likewise the 'vertDim' name with its value vDim. Here are several possible calling syntaxes for the function:

photoPrint(filename, format);
photoPrint(filename, format, finish)
photoPrint(filename, format, finish, colorCode)
photoPrint(filename, format, finish, colorCode, ...
   'horizDim', hDim)
photoPrint(filename, format, finish, colorCode, ...
   'vertDim', vDim)

Begin writing the example function photoPrint by entering the following two statements into a file named photoPrint.m. The second statement calls the class constructor for inputParser to create an instance p of the class. This class instance, or object, gives you access to all of the methods and properties of the class:

function photoPrint(filename, format, varargin)
p = inputParser;    % Create an instance of the class.

Add the following code to the photoPrint function. These statements call the addRequired, addOptional, and addParamValue methods to define the types of input data one can pass to this function:

p.addRequired('filename', @ischar);
p.addRequired('format', @(x)strcmp(x,'jpeg') ...
   || strcmp(x,'tiff'));

p.addOptional('finish', 'glossy', @(x)strcmpi(x,'flat') ...
   || strcmpi(x,'glossy'));
p.addOptional('colorCode', 'CMYK', @(x)strcmpi(x,'CMYK') ...
   || strcmpi(x,'RGB'));

p.addParamValue('horizDim', 6, @(x)isnumeric(x) && x<=20));
p.addParamValue('vertDim', 4, @(x)isnumeric(x) && x<=20));

Just after this, call the parse method to parse and validate the inputs. MATLAB puts the results of the parse into a property named Results:

p.parse(filename, format, varargin{:});
p.Results

Save and execute the file, passing the required and any number of the optional input arguments. Examining p.Results displays the name of each input as a field, and the value of each input as the value of that field:

photoPrint('myPhoto', 'tiff', 'flat', 'RGB', ...
           'horizDim', 10, 'vertDim', 8)

The following inputs have been received and validated:
    colorCode: 'RGB'
     filename: 'myPhoto'
       finish: 'flat'
       format: 'tiff'
     horizDim: 10
      vertDim: 8

See Also

inputParser, addRequired(inputParser), addParamValue(inputParser), parse(inputParser), createCopy(inputParser)

© 1984-2010- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS