getargs.m

process parameter name/value pairs

getargs() processes parameter name/value pairs, allowing a function with a large number of optional input parameters to be called with values being provided only for those parameters whose names are passed (all other parameters receive default values). The syntax is as follows:

[eid,emsg,a,b,...]= getargs(pnames,dflts,'name1',val1,'name2',val2,...)

This function, which is based on statgetargs(), accepts a cell array pnames of valid parameter names, a cell array dflts of default values for the parameters named in pnames, and additional parameter name/value pairs. Unlike statgetargs(), parameter getargs() does case sensitive parameter name comparisons.

getargs() returns parameter values A,B,... in the same order as the names in pnames. Outputs corresponding to entries in pnames that are not specified in the name/value pairs are set to the corresponding value from DFLTS. If nargout is equal to length(pnames)+1, then unrecognized name/value pairs are an error. If nargout is equal to length(pnames)+2, then all unrecognized name/value pairs are returned in a single cell array following any other outputs.

EID and EMSG are empty if the arguments are valid. If an error occurs, EMSG is the text of an error message and EID is the final component of an error message id. getargs() does not actually throw any errors, but rather returns EID and EMSG so that the caller may throw the error. Outputs will be partially processed after an error occurs.

This utility is used by some Statistics Toolbox functions to process name/value pair arguments.

Example:
pnames = {'color' 'linestyle', 'linewidth'}
dflts = { 'r' '_' '1'}
varargin = {{'linew' 2 'nonesuch' [1 2 3] 'linestyle' ':'}
[eid,emsg,c,ls,lw] = getargs(pnames,dflts,varargin{:}) % error
[eid,emsg,c,ls,lw,ur] = getargs(pnames,dflts,varargin{:}) % ok

We always create (nparams+2) outputs:
one each for emsg and eid
nparams varargs for values corresponding to names in pnames

If the calling program asks for one more (nargout == nparams+3), it's for unrecognized names/values.