argcheck

Sets missing input args to the defaults, does argument checking, and handles property id/value lists

USAGE: [err, <outargs>]= argcheck(maxargs, inargs, defaults) [err, <outargs>]= argcheck(maxargs, inargs, defaults, <check list>)

Sets missing input args to the defaults, does argument checking, and handles property id/value lists. Although not slow, the emphasis is on error checking, not on speed. If a value is tagged as 'proplist' the property id/value list will be returned as a structure. Further, if the default value for it is a structure, only property ids that are field names of the structure are allowed (the structure's field names must be lower case!). If you don't want this check, make the default an empty value, e.g. {}.

EXAMPLES:
Say you have three arguments x, a, and b, the two latter optional with default values a=0 and b=1.
Using the function declaration 'function whateverout= funcname(varargin)' you would call
[err, x, a, b]= argcheck(3, varargin, {0, 1});
You want to check if you can do an elemetwise calculation with x, a, b, e.g. x.*a+b:
[err, x, a, b]= argcheck(3, varargin, {0, 1}, 'mathsize');
And b must be positive:
[err, x, a, b]= argcheck(3, varargin, {0, 1}, 'mathsize', 'positive', [3]);
Maybe we want an optional property id/value list:
[err, x, a, b, p]= argcheck(4, varargin, {0, 1, {}}, ... 'mathsize', [1 2 3], 'positive', [3], 'proplist', [4]);
If the returned err is not empty, signal an error with it:
if(~isempty(err)), error(err); end

ARGUMENTS:
err: Error message. If empty, all went well.
<outargs>: A list of receiving variables, there must be exactly maxargs of them.
maxargs: Maximum number of arguments, a positive integer scalar.
inargs: The original input arguments, a cell vector.
defaults: Default values, a cell vector, where length(defaults) <= length(inargs) <= maxargs.
<check list>: An optional list that specifies what tests the arguments should pass. Each test specification consists of the test id (a string, see below) and an optional argument index specifying the the test arguments (an array with inargs indeces).

TEST IDS:
Check arguments' dimensions:
- 'length' Arguments are of the same length, uses length(arg).
- 'mathlength' Arguments are non-empty, numeric, and of the same length or scalar.
- 'length=N' Arguments are of length N, uses length(arg) == N.
- 'mathlength=N' Arguments are non-empty, numeric, and of length N or scalar.
- 'size' Arguments are of the same size.
- 'mathsize' Arguments are non-empty, numeric, and of the same size or scalar.
- 'size1=N' Arguments are have N rows, uses size(arg, 1) == N.
- 'size2=N' Arguments are have N columns, uses size(arg, 2) == N.
- 'non-empty' Arguments are non-empty, uses ~isempty(arg).
- 'scalar' Arguments are scalars, uses isscalar.
- 'vector' Arguments are vectors, uses isvector.
- 'colvector' Arguments are column vectors.
- 'rowvector' Arguments are row vectors.
- 'square' Arguments are non-empty, numeric, square, and two-dimensional arrays.
- 'dim=N' Arguments are of dimension N, uses ndims(arg) == N.
Check argument values:
- 'numeric' Arguments are numeric arrays, uses isa(arg, 'numeric').
- 'real' Arguments are numeric real arrays, uses isa(arg, 'real').
- 'finite' Arguments are of only finite elements, uses all(isfinite(arg)).
- 'int' Arguments are integer values (use 'integer' for integer TYPES, see below).
- 'positive' Arguments are of only positiv elements.
- 'non-positive' Arguments are of only non-positiv elements.
- 'negative' Arguments are of only negative elements.
- 'non-negative' Arguments are of only non-negative elements.
- 'non-zero' Arguments are of only non-zero elements.
- 'proplist' Arguments are property lists -- a cell array with an even number of items where the first, third etc. items are strings (property identifiers).
- 'directory' Arguments are directories, uses isdir(arg).
Check arguments' class:
- 'cellstr' Arguments are cell array of strings, uses iscellstr(arg).
- 'string' Arguments are char or cellstr.
- 'float' Arguments are floating-point arrays, uses isa(arg, 'float').
- 'integer' Arguments are of integer data types, uses isa(arg, 'integer').
- 'sym' Arguments are symbolic expression, uses isa(arg, 'sym').
- '<other>' Arguments are of a given class, uses isa(arg, 'TAG'), e.g. sym, logical, char, single, double, cell, struct, function_handle, int8, uint8, int16, uint16, int32, uint32, int64, uint64, or any other class.

HISTORY:
Version 1.0, 2006-11-16.
Version 1.1, 2006-11-23.
- Added check for allowed property ids in property id/value lists.
- Added structure generation from property id/value lists.
Version 1.2, 2006-11-27.
- Returned arguments are no longer made into NaNs if there was an error.
- Removed some unnecessary case sensitivity.
- Added check for integer values, tag 'int'.
- Clarified examples.

COPYRIGHT (C) Peder Axensten <peder at axensten dot se>