% -*- texinfo -*-
% @deftypefn {Function File} {} arrayfun (@var{func}, @var{a})
% @deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{a})
% @deftypefnx {Function File} {@var{x} =} arrayfun (@var{func}, @var{a}, @var{b}, @dots{})
% @deftypefnx {Function File} {[@var{x}, @var{y}, @dots{}] =} arrayfun (@var{func}, @var{a}, @dots{})
% @deftypefnx {Function File} {} arrayfun (@dots{}, 'UniformOutput', @var{val})
% @deftypefnx {Function File} {} arrayfun (@dots{}, 'ErrorHandler', @var{errfunc})
%
% Execute a function on each element of an array. This is useful for
% functions that do not accept array arguments. If the function does
% accept array arguments it is better to call the function directly.
%
% The first input argument @var{func} can be a string, a function
% handle, an inline function or an anonymous function. The input
% argument @var{a} can be a logic array, a numeric array, a string
% array, a structure array or a cell array. By a call of the function
% @command{arrayfun} all elements of @var{a} are passed on to the named
% function @var{func} individually.
%
% The named function can also take more than two input arguments, with
% the input arguments given as third input argument @var{b}, fourth
% input argument @var{c}, @dots{} If given more than one array input
% argument then all input arguments must have the same sizes, for
% example
%
% @example
% @group
% arrayfun (@@atan2, [1, 0], [0, 1])
% @result{} ans = [1.5708 0.0000]
% @end group
% @end example
%
% If the parameter @var{val} after a further string input argument
% 'UniformOutput' is set @code{true} (the default), then the named
% function @var{func} must return a single element which then will be
% concatenated into the return value and is of type matrix. Otherwise,
% if that parameter is set to @code{false}, then the outputs are
% concatenated in a cell array. For example
%
% @example
% @group
% arrayfun (@@(x,y) x:y, 'abc', 'def', 'UniformOutput', false)
% @result{} ans =
% @{
% [1,1] = abcd
% [1,2] = bcde
% [1,3] = cdef
% @}
% @end group
% @end example
%
% If more than one output arguments are given then the named function
% must return the number of return values that also are expected, for
% example
%
% @example
% @group
% [A, B, C] = arrayfun (@@find, [10; 0], 'UniformOutput', false)
% @result{}
% A =
% @{
% [1,1] = 1
% [2,1] = [](0x0)
% @}
% B =
% @{
% [1,1] = 1
% [2,1] = [](0x0)
% @}
% C =
% @{
% [1,1] = 10
% [2,1] = [](0x0)
% @}
% @end group
% @end example
%
% If the parameter @var{errfunc} after a further string input argument
% 'ErrorHandler' is another string, a function handle, an inline
% function or an anonymous function, then @var{errfunc} defines a
% function to call in the case that @var{func} generates an error.
% The definition of the function must be of the form
%
% @example
% function [@dots{}] = errfunc (@var{s}, @dots{})
% @end example
%
% where there is an additional input argument to @var{errfunc}
% relative to @var{func}, given by @var{s}. This is a structure with
% the elements 'identifier', 'message' and 'index', giving
% respectively the error identifier, the error message and the index of
% the array elements that caused the error. The size of the output
% argument of @var{errfunc} must have the same size as the output
% argument of @var{func}, otherwise a real error is thrown. For
% example
%
% @example
% @group
% function y = ferr (s, x), y = 'MyString';
% arrayfun (@@str2num, [1234], ...
% 'UniformOutput', false, 'ErrorHandler', @@ferr)
% @result{} ans =
% @{
% [1,1] = MyString
% @}
% @end group
% @end example
%
% @seealso{cellfun, spfun, structfun}
% @end deftypefn