<html lang="en">
<head>
<title>Function Application - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution" title="Vectorization and Faster Code Execution">
<link rel="prev" href="Broadcasting.html#Broadcasting" title="Broadcasting">
<link rel="next" href="Accumulation.html#Accumulation" title="Accumulation">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Function-Application"></a>
<p>
Next: <a rel="next" accesskey="n" href="Accumulation.html#Accumulation">Accumulation</a>,
Previous: <a rel="previous" accesskey="p" href="Broadcasting.html#Broadcasting">Broadcasting</a>,
Up: <a rel="up" accesskey="u" href="Vectorization-and-Faster-Code-Execution.html#Vectorization-and-Faster-Code-Execution">Vectorization and Faster Code Execution</a>
<hr>
</div>
<h3 class="section">19.3 Function Application</h3>
<p><a name="index-map-2132"></a><a name="index-apply-2133"></a><a name="index-function-application-2134"></a>
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 src/DLD-FUNCTIONS/cellfun.cc -->
<p><a name="doc_002darrayfun"></a>
<div class="defun">
— Function File: <b>arrayfun</b> (<var>func, A</var>)<var><a name="index-arrayfun-2135"></a></var><br>
— Function File: <var>x</var> = <b>arrayfun</b> (<var>func, A</var>)<var><a name="index-arrayfun-2136"></a></var><br>
— Function File: <var>x</var> = <b>arrayfun</b> (<var>func, A, b, <small class="dots">...</small></var>)<var><a name="index-arrayfun-2137"></a></var><br>
— Function File: [<var>x</var>, <var>y</var>, <small class="dots">...</small>] = <b>arrayfun</b> (<var>func, A, <small class="dots">...</small></var>)<var><a name="index-arrayfun-2138"></a></var><br>
— Function File: <b>arrayfun</b> (<var><small class="dots">...</small>, "UniformOutput", val</var>)<var><a name="index-arrayfun-2139"></a></var><br>
— Function File: <b>arrayfun</b> (<var><small class="dots">...</small>, "ErrorHandler", errfunc</var>)<var><a name="index-arrayfun-2140"></a></var><br>
<blockquote>
<p>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.
<p>The first input argument <var>func</var> can be a string, a function
handle, an inline function, or an anonymous function. The input
argument <var>A</var> can be a logic array, a numeric array, a string
array, a structure array, or a cell array. By a call of the function
<samp><span class="command">arrayfun</span></samp> all elements of <var>A</var> are passed on to the named
function <var>func</var> individually.
<p>The named function can also take more than two input arguments, with
the input arguments given as third input argument <var>b</var>, fourth
input argument <var>c</var>, <small class="dots">...</small> If given more than one array input
argument then all input arguments must have the same sizes, for
example:
<pre class="example"> arrayfun (@atan2, [1, 0], [0, 1])
⇒ ans = [1.5708 0.0000]
</pre>
<p>If the parameter <var>val</var> after a further string input argument
"UniformOutput" is set <code>true</code> (the default), then the named
function <var>func</var> 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</code>, then the outputs are
concatenated in a cell array. For example:
<pre class="example"> arrayfun (@(x,y) x:y, "abc", "def", "UniformOutput", false)
⇒ ans =
{
[1,1] = abcd
[1,2] = bcde
[1,3] = cdef
}
</pre>
<p>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:
<pre class="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)
}
</pre>
<p>If the parameter <var>errfunc</var> after a further string input argument
"ErrorHandler" is another string, a function handle, an inline
function, or an anonymous function, then <var>errfunc</var> defines a
function to call in the case that <var>func</var> generates an error.
The definition of the function must be of the form
<pre class="example"> function [...] = errfunc (<var>s</var>, ...)
</pre>
<p class="noindent">where there is an additional input argument to <var>errfunc</var>
relative to <var>func</var>, given by <var>s</var>. 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</var> must have the same size as the output
argument of <var>func</var>, otherwise a real error is thrown. For
example:
<pre class="example"> function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@str2num, [1234],
"UniformOutput", false, "ErrorHandler", @ferr)
⇒ ans =
{
[1,1] = MyString
}
</pre>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dspfun.html#doc_002dspfun">spfun</a>, <a href="doc_002dcellfun.html#doc_002dcellfun">cellfun</a>, <a href="doc_002dstructfun.html#doc_002dstructfun">structfun</a>.
</p></blockquote></div>
<!-- spfun scripts/sparse/spfun.m -->
<p><a name="doc_002dspfun"></a>
<div class="defun">
— Function File: <var>y</var> = <b>spfun</b> (<var>f, S</var>)<var><a name="index-spfun-2141"></a></var><br>
<blockquote><p>Compute <code>f(</code><var>S</var><code>)</code> for the non-zero values of <var>S</var>.
This results in a sparse matrix with the same structure as
<var>S</var>. The function <var>f</var> can be passed as a string, a
function handle, or an inline function.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002darrayfun.html#doc_002darrayfun">arrayfun</a>, <a href="doc_002dcellfun.html#doc_002dcellfun">cellfun</a>, <a href="doc_002dstructfun.html#doc_002dstructfun">structfun</a>.
</p></blockquote></div>
<!-- cellfun src/DLD-FUNCTIONS/cellfun.cc -->
<p><a name="doc_002dcellfun"></a>
<div class="defun">
— Loadable Function: <b>cellfun</b> (<var>name, C</var>)<var><a name="index-cellfun-2142"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var>"size", C, k</var>)<var><a name="index-cellfun-2143"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var>"isclass", C, class</var>)<var><a name="index-cellfun-2144"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var>func, C</var>)<var><a name="index-cellfun-2145"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var>func, C, D</var>)<var><a name="index-cellfun-2146"></a></var><br>
— Loadable Function: [<var>a</var>, <small class="dots">...</small>] = <b>cellfun</b> (<var><small class="dots">...</small></var>)<var><a name="index-cellfun-2147"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var><small class="dots">...</small>, 'ErrorHandler', errfunc</var>)<var><a name="index-cellfun-2148"></a></var><br>
— Loadable Function: <b>cellfun</b> (<var><small class="dots">...</small>, 'UniformOutput', val</var>)<var><a name="index-cellfun-2149"></a></var><br>
<blockquote>
<p>Evaluate the function named <var>name</var> on the elements of the cell array
<var>C</var>. Elements in <var>C</var> are passed on to the named function
individually. The function <var>name</var> can be one of the functions
<dl>
<dt><code>isempty</code><dd>Return 1 for empty elements.
<br><dt><code>islogical</code><dd>Return 1 for logical elements.
<br><dt><code>isreal</code><dd>Return 1 for real elements.
<br><dt><code>length</code><dd>Return a vector of the lengths of cell elements.
<br><dt><code>ndims</code><dd>Return the number of dimensions of each element.
<br><dt><code>numel</code><dt><code>prodofsize</code><dd>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.
<br><dt><code>size</code><dd>Return the size along the <var>k</var>-th dimension.
<br><dt><code>isclass</code><dd>Return 1 for elements of <var>class</var>.
</dl>
<p>Additionally, <code>cellfun</code> accepts an arbitrary function <var>func</var>
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 <var>x</var>, and
it must return a string value. The function can take one or more arguments,
with the inputs arguments given by <var>C</var>, <var>D</var>, etc. Equally the
function can return one or more output arguments. For example:
<pre class="example"> cellfun ("atan2", {1, 0}, {0, 1})
⇒ans = [1.57080 0.00000]
</pre>
<p>The number of output arguments of <code>cellfun</code> matches the number of output
arguments of the function. The outputs of the function will be collected
into the output arguments of <code>cellfun</code> like this:
<pre class="example"> 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
</pre>
<p>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.
<p>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:
<pre class="example"> cellfun ("tolower", {"Foo", "Bar", "FooBar"},
"UniformOutput",false)
⇒ ans = {"foo", "bar", "foobar"}
</pre>
<p>Given the parameter 'ErrorHandler', then <var>errfunc</var> defines a function to
call in case <var>func</var> generates an error. The form of the function is
<pre class="example"> function [...] = errfunc (<var>s</var>, ...)
</pre>
<p class="noindent">where there is an additional input argument to <var>errfunc</var> relative to
<var>func</var>, given by <var>s</var>. 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:
<pre class="example"> function y = foo (s, x), y = NaN; endfunction
cellfun ("factorial", {-1,2}, 'ErrorHandler', @foo)
⇒ ans = [NaN 2]
</pre>
<p>Use <code>cellfun</code> intelligently. The <code>cellfun</code> 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:
<pre class="example"> a = {...}
v = cellfun (@(x) det(x), a); # compute determinants
v = cellfun (@det, a); # faster
</pre>
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002darrayfun.html#doc_002darrayfun">arrayfun</a>, <a href="doc_002dstructfun.html#doc_002dstructfun">structfun</a>, <a href="doc_002dspfun.html#doc_002dspfun">spfun</a>.
</p></blockquote></div>
<!-- structfun scripts/general/structfun.m -->
<p><a name="doc_002dstructfun"></a>
<div class="defun">
— Function File: <b>structfun</b> (<var>func, S</var>)<var><a name="index-structfun-2150"></a></var><br>
— Function File: [<var>A</var>, <small class="dots">...</small>] = <b>structfun</b> (<var><small class="dots">...</small></var>)<var><a name="index-structfun-2151"></a></var><br>
— Function File: <b>structfun</b> (<var><small class="dots">...</small>, "ErrorHandler", errfunc</var>)<var><a name="index-structfun-2152"></a></var><br>
— Function File: <b>structfun</b> (<var><small class="dots">...</small>, "UniformOutput", val</var>)<var><a name="index-structfun-2153"></a></var><br>
<blockquote>
<p>Evaluate the function named <var>name</var> on the fields of the structure
<var>S</var>. The fields of <var>S</var> are passed to the function <var>func</var>
individually.
<p><code>structfun</code> accepts an arbitrary function <var>func</var> 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 <var>x</var>, and it must return
a string value. If the function returns more than one argument, they are
returned as separate output variables.
<p>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.
<pre class="example"> s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s,
"UniformOutput", false)
⇒
{
name1 = Smith
name2 = Jones
}
</pre>
<p>Given the parameter "ErrorHandler", <var>errfunc</var> defines a function to
call in case <var>func</var> generates an error. The form of the function is
<pre class="example"> function [...] = errfunc (<var>se</var>, ...)
</pre>
<p class="noindent">where there is an additional input argument to <var>errfunc</var> relative to
<var>func</var>, given by <var>se</var>. 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, see <a href="doc_002dcellfun.html#doc_002dcellfun"><code>cellfun</code></a>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dcellfun.html#doc_002dcellfun">cellfun</a>, <a href="doc_002darrayfun.html#doc_002darrayfun">arrayfun</a>, <a href="doc_002dspfun.html#doc_002dspfun">spfun</a>.
</p></blockquote></div>
</body></html>
