parseParameters(Defaults, callerVarargin, varargin)
Parses parameter name-value pairs quickly. Does not handle options.
Within yourFunction(...)
, specify defaults in a struct:
Defaults.x = 1; Defaults.y = 1;
Then call [x,y] =
parseParameters(Defaults,varargin);
The user can then call
yourFunction(...,'Y',2,'x',3);
to change x and y. See Examples
section for more. This function combines brevity in usage, high
performance, and the convenience and clarity of parameter
name-value pairs. MATLAB's inputParser class is relatively slow.
Simpler methods are verbose and/or only handle positional
arguments. Many FEX parameter parsing solutions use assignin, which
is convenient, but also slow and unsafe.
Parameters: |
|
---|---|
Returns: | varargout (cell) -- The values of the parameters, returned in the same order as the Defaults struct fields were initialized. If expandStruct is false, returns a struct formatted like the Defaults struct. |
inputParser()
In my tests this function is 9-20x faster than inputParser. To keep your programs responsive, use inputParser for functions called less than 1000 times and parseParameters for functions called less than 10,000 times. I recommend positional argument parsing with nargin instead of name-value pairs for functions called less than 100,000 times. Any more and consider not using optional arguments.
Positional argument parsing methods include using exist, cell arrays, and nargin. parseParameters is nearly on par with the exist method, 2-3x slower than the cell method, and 7-10x slower than the nargin method.
I sacrificed features for performance. Users may be interested in other solutions with more features. I tested the performance of several FEX parameter name-value pair parsing functions. The fastest was loadOptions by N. Brahms. The syntax is verbose, but it is only a tad (1.2-1.5x) slower than parseParameters and allows for type checking. Other fairly fast FEX solutions are getargs, parseargs, and parse_pv_pairs.
Here's an extra tip. To make MATLAB's inputParser more concise, use:
>> results = struct2cell(p.Results);
>> [param1, param2, param3] = results{:};
Note: This documentation adheres to NumPy-style (see link below). It is compatible with Sphinx using the matlabdomain and napoleon extensions. https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Basic usage within a function:
function foo(varargin)
Defaults.a = 'a';
Defaults.b = 'b';
[a,b] = parseParameters(Defaults,varargin);
disp(['a: ' a ', b: ' b '.']);
end
>> foo('a','A')
a: A, b: b.
Order of Defaults initialization matters. Case insensitive by default:
>> Defaults.x = 3.14159;
>> Defaults.msg = 'hello';
>> [x,msg] = parseParameters(Defaults,{'MsG','bye','x',1.61803})
x = 1.61803
msg = 'bye'
Using case sensitivity and returning a structure:
function foo(varargin)
Defaults.FOOL = 1;
Defaults.food = 'apple';
Fooey = parseParameters(Defaults,varargin,true,false);
disp(Fooey);
end
>> foo('food','orange','fool',0)
FOOL: 1
food: 'orange'
Notice that Fooey.FOOL was not changed. The options support using empty arrays for defaults.
Copyright 2015 Jeffrey Chiou and everyone else. Feel free to copy, distribute, and modify.