octave: Function Application
19.3 Function Application
=========================
As a general rule, functions should already be written with matrix
arguments in mind and should consider whole matrix operations in a
vectorized manner. Sometimes, writing functions in this way appears
difficult or impossible for various reasons. For those situations,
Octave provides facilities for applying a function to each element of an
array, cell, or struct.
-- : arrayfun (FUNC, A)
-- : X = arrayfun (FUNC, A)
-- : X = arrayfun (FUNC, A, B, ...)
-- : [X, Y, ...] = arrayfun (FUNC, A, ...)
-- : arrayfun (..., "UniformOutput", VAL)
-- : arrayfun (..., "ErrorHandler", 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 FUNC can be a string, a function handle,
an inline function, or an anonymous function. The input argument 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 ‘arrayfun’ all
elements of A are passed on to the named function FUNC
individually.
The named function can also take more than two input arguments,
with the input arguments given as third input argument B, fourth
input argument C, ... If given more than one array input argument
then all input arguments must have the same sizes, for example:
arrayfun (@atan2, [1, 0], [0, 1])
⇒ [ 1.57080 0.00000 ]
If the parameter VAL after a further string input argument
"UniformOutput" is set ‘true’ (the default), then the named
function 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 ‘false’, then the outputs
are concatenated in a cell array. For example:
arrayfun (@(x,y) x:y, "abc", "def", "UniformOutput", false)
⇒
{
[1,1] = abcd
[1,2] = bcde
[1,3] = cdef
}
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:
[A, B, C] = arrayfun (@find, [10; 0], "UniformOutput", false)
⇒
A =
{
[1,1] = 1
[2,1] = [](0x0)
}
B =
{
[1,1] = 1
[2,1] = [](0x0)
}
C =
{
[1,1] = 10
[2,1] = [](0x0)
}
If the parameter ERRFUNC after a further string input argument
"ErrorHandler" is another string, a function handle, an inline
function, or an anonymous function, then ERRFUNC defines a function
to call in the case that FUNC generates an error. The definition
of the function must be of the form
function [...] = errfunc (S, ...)
where there is an additional input argument to ERRFUNC relative to
FUNC, given by 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
ERRFUNC must have the same size as the output argument of FUNC,
otherwise a real error is thrown. For example:
function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@str2num, [1234],
"UniformOutput", false, "ErrorHandler", @ferr)
⇒
{
[1,1] = MyString
}
DONTPRINTYET See also: 
spfun XREFspfun, cellfun XREFcellfun, *noteDONTPRINTYET See also: spfun XREFspfun, cellfun XREFcellfun,
structfun XREFstructfun.
-- : Y = spfun (F, S)
Compute ‘f(S)’ for the nonzero values of S.
This results in a sparse matrix with the same structure as S. The
function F can be passed as a string, a function handle, or an
inline function.
See also: arrayfun XREFarrayfun, cellfun XREFcellfun,
structfun XREFstructfun.
-- : cellfun (NAME, C)
-- : cellfun ("size", C, K)
-- : cellfun ("isclass", C, CLASS)
-- : cellfun (FUNC, C)
-- : cellfun (FUNC, C, D)
-- : [A, ...] = cellfun (...)
-- : cellfun (..., "ErrorHandler", ERRFUNC)
-- : cellfun (..., "UniformOutput", VAL)
Evaluate the function named NAME on the elements of the cell array
C.
Elements in C are passed on to the named function individually.
The function NAME can be one of the functions
‘isempty’
Return 1 for empty elements.
‘islogical’
Return 1 for logical elements.
‘isnumeric’
Return 1 for numeric elements.
‘isreal’
Return 1 for real elements.
‘length’
Return a vector of the lengths of cell elements.
‘ndims’
Return the number of dimensions of each element.
‘numel’
‘prodofsize’
Return the number of elements contained within each cell
element. The number is the product of the dimensions of the
object at each cell element.
‘size’
Return the size along the K-th dimension.
‘isclass’
Return 1 for elements of CLASS.
Additionally, ‘cellfun’ accepts an arbitrary function FUNC in the
form of an inline function, function handle, or the name of a
function (in a character string). The function can take one or
more arguments, with the inputs arguments given by C, D, etc.
Equally the function can return one or more output arguments. For
example:
cellfun ("atan2", {1, 0}, {0, 1})
⇒ [ 1.57080 0.00000 ]
The number of output arguments of ‘cellfun’ matches the number of
output arguments of the function. The outputs of the function will
be collected into the output arguments of ‘cellfun’ like this:
function [a, b] = twoouts (x)
a = x;
b = x*x;
endfunction
[aa, bb] = cellfun (@twoouts, {1, 2, 3})
⇒
aa =
1 2 3
bb =
1 4 9
Note that per default the output argument(s) are arrays of the same
size as the input arguments. Input arguments that are singleton
(1x1) cells will be automatically expanded to the size of the other
arguments.
If the parameter "UniformOutput" is set to true (the default), then
the function must return scalars which will be concatenated into
the return array(s). If "UniformOutput" is false, the outputs are
concatenated into a cell array (or cell arrays). For example:
cellfun ("tolower", {"Foo", "Bar", "FooBar"},
"UniformOutput", false)
⇒ {"foo", "bar", "foobar"}
Given the parameter "ErrorHandler", then ERRFUNC defines a function
to call in case FUNC generates an error. The form of the function
is
function [...] = errfunc (S, ...)
where there is an additional input argument to ERRFUNC relative to
FUNC, given by S. This is a structure with the elements
"identifier", "message", and "index" giving respectively the error
identifier, the error message, and the index into the input
arguments of the element that caused the error. For example:
function y = foo (s, x), y = NaN; endfunction
cellfun ("factorial", {-1,2}, "ErrorHandler", @foo)
⇒ [NaN 2]
Use ‘cellfun’ intelligently. The ‘cellfun’ function is a useful
tool for avoiding loops. It is often used with anonymous function
handles; however, calling an anonymous function involves an
overhead quite comparable to the overhead of an m-file function.
Passing a handle to a built-in function is faster, because the
interpreter is not involved in the internal loop. For example:
a = {...}
v = cellfun (@(x) det (x), a); # compute determinants
v = cellfun (@det, a); # faster
DONTPRINTYET See also: arrayfun XREFarrayfun, *notestructfun:
DONTPRINTYET See also: arrayfun XREFarrayfun, structfun
XREFstructfun, spfun XREFspfun.
-- : structfun (FUNC, S)
-- : [A, ...] = structfun (...)
-- : structfun (..., "ErrorHandler", ERRFUNC)
-- : structfun (..., "UniformOutput", VAL)
Evaluate the function named NAME on the fields of the structure S.
The fields of S are passed to the function FUNC individually.
‘structfun’ accepts an arbitrary function FUNC in the form of an
inline function, function handle, or the name of a function (in a
character string). In the case of a character string argument, the
function must accept a single argument named X, and it must return
a string value. If the function returns more than one argument,
they are returned as separate output variables.
If the parameter "UniformOutput" is set to true (the default), then
the function must return a single element which will be
concatenated into the return value. If "UniformOutput" is false,
the outputs are placed into a structure with the same fieldnames as
the input structure.
s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s,
"UniformOutput", false)
⇒
{
name1 = Smith
name2 = Jones
}
Given the parameter "ErrorHandler", ERRFUNC defines a function to
call in case FUNC generates an error. The form of the function is
function [...] = errfunc (SE, ...)
where there is an additional input argument to ERRFUNC relative to
FUNC, given by SE. This is a structure with the elements
"identifier", "message" and "index", giving respectively the error
identifier, the error message, and the index into the input
arguments of the element that caused the error. For an example on
how to use an error handler, cellfun XREFcellfun.
See also: cellfun XREFcellfun, arrayfun XREFarrayfun,
spfun XREFspfun.
Consistent with earlier advice, seek to use Octave built-in functions
whenever possible for the best performance. This advice applies
especially to the four functions above. For example, when adding two
arrays together element-by-element one could use a handle to the
built-in addition function ‘@plus’ or define an anonymous function
‘@(x,y) x + y’. But, the anonymous function is 60% slower than the
first method. Operator Overloading, for a list of basic
functions which might be used in place of anonymous ones.
Info Catalog
octave: Broadcasting
octave: Vectorization and Faster Code Execution
octave: Accumulation