1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Function Application (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Function Application (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Function Application (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Vectorization-and-Faster-Code-Execution.html" rel="up" title="Vectorization and Faster Code Execution">
<link href="Accumulation.html" rel="next" title="Accumulation">
<link href="Broadcasting.html" rel="prev" title="Broadcasting">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="section-level-extent" id="Function-Application">
<div class="nav-panel">
<p>
Next: <a href="Accumulation.html" accesskey="n" rel="next">Accumulation</a>, Previous: <a href="Broadcasting.html" accesskey="p" rel="prev">Broadcasting</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html" accesskey="u" rel="up">Vectorization and Faster Code Execution</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h3 class="section" id="Function-Application-1"><span>19.3 Function Application<a class="copiable-link" href="#Function-Application-1"> ¶</a></span></h3>
<a class="index-entry-id" id="index-map"></a>
<a class="index-entry-id" id="index-apply"></a>
<a class="index-entry-id" id="index-function-application"></a>
<p>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.
</p>
<a class="anchor" id="XREFarrayfun"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-arrayfun"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">arrayfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">A</var>)</code><a class="copiable-link" href="#index-arrayfun"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-arrayfun-1"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">arrayfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">A1</var>, <var class="var">A2</var>, …)</code><a class="copiable-link" href="#index-arrayfun-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-arrayfun-2"><span><code class="def-type">[<var class="var">B1</var>, <var class="var">B2</var>, …] =</code> <strong class="def-name">arrayfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">A</var>, …)</code><a class="copiable-link" href="#index-arrayfun-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-arrayfun-3"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">arrayfun</strong> <code class="def-code-arguments">(…, "UniformOutput", <var class="var">val</var>)</code><a class="copiable-link" href="#index-arrayfun-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-arrayfun-4"><span><code class="def-type"><var class="var">B</var> =</code> <strong class="def-name">arrayfun</strong> <code class="def-code-arguments">(…, "ErrorHandler", <var class="var">errfcn</var>)</code><a class="copiable-link" href="#index-arrayfun-4"> ¶</a></span></dt>
<dd>
<p>Execute a function on each element of an array.
</p>
<p>This is useful for functions that do not accept array arguments. If the
function does accept array arguments it is <em class="emph">better</em> to call the function
directly.
</p>
<p>The first input argument <var class="var">fcn</var> can be a string, a function handle, an
inline function, or an anonymous function. The input argument <var class="var">A</var> can be a
logical array, a numeric array, a string array, a structure array, or a cell
array. <code class="code">arrayfun</code> passes all elements of <var class="var">A</var> individually to the
function <var class="var">fcn</var> and collects the results. The equivalent pseudo-code is
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">cls = class (<var class="var">fcn</var> (<var class="var">A</var>(1));
<var class="var">B</var> = zeros (size (<var class="var">A</var>), cls);
for i = 1:numel (<var class="var">A</var>)
<var class="var">B</var>(i) = <var class="var">fcn</var> (<var class="var">A</var>(i))
endfor
</pre></div></div>
<p>The named function can also take more than two input arguments, with the input
arguments given as third input argument <var class="var">A2</var>, fourth input argument
<var class="var">A2</var>, <small class="enddots">...</small> If given more than one array input argument then all
input arguments must have the same sizes. For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">arrayfun (@atan2, [1, 0], [0, 1])
⇒ [ 1.57080 0.00000 ]
</pre></div></div>
<p>If the parameter <var class="var">val</var> after a further string input argument
<code class="code">"UniformOutput"</code> is set <code class="code">true</code> (the default), then the named
function <var class="var">fcn</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 class="code">false</code>, then the outputs are concatenated in a cell array. For
example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">arrayfun (@(x,y) x:y, "abc", "def", "UniformOutput", false)
⇒
{
[1,1] = abcd
[1,2] = bcde
[1,3] = cdef
}
</pre></div></div>
<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:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">[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></div></div>
<p>If the parameter <var class="var">errfcn</var> after a further string input argument
<code class="code">"ErrorHandler"</code> is another string, a function handle, an inline
function, or an anonymous function, then <var class="var">errfcn</var> defines a function to
call in the case that <var class="var">fcn</var> generates an error. The definition of the
function must be of the form
</p>
<div class="example">
<pre class="example-preformatted">function [...] = errfcn (<var class="var">s</var>, ...)
</pre></div>
<p>where there is an additional input argument to <var class="var">errfcn</var> relative to
<var class="var">fcn</var>, given by <var class="var">s</var>. This is a structure with the elements
<code class="code">"identifier"</code>, <code class="code">"message"</code>, and <code class="code">"index"</code> 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 class="var">errfcn</var> must have the same size as the output argument of <var class="var">fcn</var>,
otherwise a real error is thrown. For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">function y = ferr (s, x), y = "MyString"; endfunction
arrayfun (@str2num, [1234],
"UniformOutput", false, "ErrorHandler", @ferr)
⇒
{
[1,1] = MyString
}
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFspfun">spfun</a>, <a class="ref" href="#XREFcellfun">cellfun</a>, <a class="ref" href="#XREFstructfun">structfun</a>.
</p></dd></dl>
<a class="anchor" id="XREFspfun"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-spfun"><span><code class="def-type"><var class="var">y</var> =</code> <strong class="def-name">spfun</strong> <code class="def-code-arguments">(<var class="var">f</var>, <var class="var">S</var>)</code><a class="copiable-link" href="#index-spfun"> ¶</a></span></dt>
<dd><p>Compute <code class="code">f (<var class="var">S</var>)</code> for the nonzero elements of <var class="var">S</var>.
</p>
<p>The input function <var class="var">f</var> is applied only to the nonzero elements of
the input matrix <var class="var">S</var> which is typically sparse. The function <var class="var">f</var>
can be passed as a string, function handle, or inline function.
</p>
<p>The output <var class="var">y</var> is a sparse matrix with the same sparsity structure as
the input <var class="var">S</var>. <code class="code">spfun</code> preserves sparsity structure which is
different than simply applying the function <var class="var">f</var> to the sparse matrix
<var class="var">S</var> when <code class="code"><var class="var">f</var> (0) != 0</code>.
</p>
<p>Example
</p>
<p>Sparsity preserving <code class="code">spfun</code> versus normal function application
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">S = pi * speye (2,2)
S =
Compressed Column Sparse (rows = 2, cols = 2, nnz = 2 [50%])
(1, 1) -> 3.1416
(2, 2) -> 3.1416
y = spfun (@cos, S)
y =
Compressed Column Sparse (rows = 2, cols = 2, nnz = 2 [50%])
(1, 1) -> -1
(2, 2) -> -1
</pre></div><pre class="example-preformatted">
</pre><div class="group"><pre class="example-preformatted">y = cos (S)
y =
Compressed Column Sparse (rows = 2, cols = 2, nnz = 4 [100%])
(1, 1) -> -1
(2, 1) -> 1
(1, 2) -> 1
(2, 2) -> -1
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFarrayfun">arrayfun</a>, <a class="ref" href="#XREFcellfun">cellfun</a>, <a class="ref" href="#XREFstructfun">structfun</a>.
</p></dd></dl>
<a class="anchor" id="XREFcellfun"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-cellfun"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(@<var class="var">fcn</var>, <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-1"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">("<var class="var">fcn</var>", <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-2"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-3"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">C1</var>, <var class="var">C2</var>, …)</code><a class="copiable-link" href="#index-cellfun-3"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-4"><span><code class="def-type">[<var class="var">A1</var>, <var class="var">A2</var>, …] =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-cellfun-4"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-5"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(…, "UniformOutput", <var class="var">val</var>)</code><a class="copiable-link" href="#index-cellfun-5"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-6"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">(…, "ErrorHandler", <var class="var">errfcn</var>)</code><a class="copiable-link" href="#index-cellfun-6"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-7"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('isempty', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-7"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-8"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('islogical', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-8"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-9"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('isnumeric', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-9"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-10"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('isreal', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-10"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-11"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('length', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-11"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-12"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('numel', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-12"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-13"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('prodofsize', <var class="var">C</var>)</code><a class="copiable-link" href="#index-cellfun-13"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-14"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('size', <var class="var">C</var>, <var class="var">dim</var>)</code><a class="copiable-link" href="#index-cellfun-14"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-cellfun-15"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">cellfun</strong> <code class="def-code-arguments">('isclass', <var class="var">C</var>, <var class="var">class</var>)</code><a class="copiable-link" href="#index-cellfun-15"> ¶</a></span></dt>
<dd>
<p>Evaluate the function <var class="var">fcn</var> on the elements of the cell array <var class="var">C</var>.
</p>
<p><code class="code">cellfun</code> accepts an arbitrary function <var class="var">fcn</var> given as a name in a
character string, as a function handle, or as an inline function. Specifying
<var class="var">fcn</var> with a character string is preferred as the performance is ~3X better
for builtin functions and equivalent for m-files.
</p>
<p><code class="code">cellfun</code> has a limited number of functions which have been
specially-coded for high-performance (~8X faster than a function handle).
These functions are only used if the function is specified by name as a string,
and only the simplest calling form—<code class="code">cellfun ('<var class="var">fcn</var>'), <var class="var">C</var>)</code><!-- /@w -->—without options is supported. If you need access to an
overloaded version of a function, such as <code class="code">numel</code> for a particular
<code class="code">classdef</code> file, then you cannot use the accelerated function name and
must use a function handle instead, e.g., <code class="code">@numel</code>.
</p>
<p>The high-performance functions are
</p>
<dl class="table">
<dt><code class="code">'isempty'</code></dt>
<dd><p>Return true for empty elements.
</p>
</dd>
<dt><code class="code">'islogical'</code></dt>
<dd><p>Return true for logical elements.
</p>
</dd>
<dt><code class="code">'isnumeric'</code></dt>
<dd><p>Return true for numeric elements.
</p>
</dd>
<dt><code class="code">'isreal'</code></dt>
<dd><p>Return true for real elements.
</p>
</dd>
<dt><code class="code">'length'</code></dt>
<dd><p>Return a vector of the lengths of cell elements.
</p>
</dd>
<dt><code class="code">'ndims'</code></dt>
<dd><p>Return the number of dimensions of each element.
</p>
</dd>
<dt><code class="code">'numel'</code></dt>
<dt><code class="code">'prodofsize'</code></dt>
<dd><p>Return the number of elements contained within each cell element. The
number is the product of the dimensions of the object of each cell element.
</p>
</dd>
<dt><code class="code">'size'</code></dt>
<dd><p>Return the size along dimension <var class="var">dim</var>.
</p>
</dd>
<dt><code class="code">'isclass'</code></dt>
<dd><p>Return true for elements which are of type <var class="var">class</var>.
</p></dd>
</dl>
<p>Elements in <var class="var">C</var> are passed to the function individually and the result of
each function invocation is collected in the output. The function can take
more than one argument with the inputs arguments given by <var class="var">C1</var>, <var class="var">C2</var>,
etc. Input arguments that are singleton (1x1) cells will be automatically
expanded to the size of the other arguments. For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">cellfun ("atan2", {1, 0}, {0, 1})
⇒ [ 1.57080 0.00000 ]
</pre></div></div>
<p>The number of output arguments of <code class="code">cellfun</code> matches the number of output
arguments of the function and can be greater than one. When there are multiple
outputs of the function they will be collected into the output arguments of
<code class="code">cellfun</code> like this:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">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></div></div>
<p>Note that, by default, the output argument(s) are arrays of the same size as
the input arguments.
</p>
<p>If the parameter <code class="code">"UniformOutput"</code> is set to true (the default), then the
function must return scalars which will be concatenated into the return
array(s). If <code class="code">"UniformOutput"</code> is false, the outputs are concatenated
into a cell array (or cell arrays). For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">cellfun ("lower", {"Foo", "Bar", "FooBar"},
"UniformOutput", false)
⇒ {"foo", "bar", "foobar"}
</pre></div></div>
<p>The parameter <code class="code">"ErrorHandler"</code> specifies a function <var class="var">errfcn</var> to call
if <var class="var">fcn</var> generates an error. The form of the function is
</p>
<div class="example">
<pre class="example-preformatted">function [...] = errfcn (<var class="var">s</var>, ...)
</pre></div>
<p>where there is an additional input argument to <var class="var">errfcn</var> relative to
<var class="var">fcn</var>, given by <var class="var">s</var>. This is a structure with the elements
<code class="code">"identifier"</code>, <code class="code">"message"</code>, and <code class="code">"index"</code> giving
respectively the error identifier, the error message, and the index into the
input arguments of the element that caused the error. For example:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">function y = foo (s, x), y = NaN; endfunction
cellfun ("factorial", {-1,2}, "ErrorHandler", @foo)
⇒ [NaN 2]
</pre></div></div>
<p>Programming Note: Use <code class="code">cellfun</code> intelligently. The <code class="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:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">C = {...}
v = cellfun (@(x) det (x), C); # compute determinants
v = cellfun (@det, C); # 40% faster
</pre></div></div>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFarrayfun">arrayfun</a>, <a class="ref" href="#XREFstructfun">structfun</a>, <a class="ref" href="#XREFspfun">spfun</a>.
</p></dd></dl>
<a class="anchor" id="XREFstructfun"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-structfun"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">structfun</strong> <code class="def-code-arguments">(<var class="var">fcn</var>, <var class="var">S</var>)</code><a class="copiable-link" href="#index-structfun"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-structfun-1"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">structfun</strong> <code class="def-code-arguments">(…, "ErrorHandler", <var class="var">errfcn</var>)</code><a class="copiable-link" href="#index-structfun-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-structfun-2"><span><code class="def-type"><var class="var">A</var> =</code> <strong class="def-name">structfun</strong> <code class="def-code-arguments">(…, "UniformOutput", <var class="var">val</var>)</code><a class="copiable-link" href="#index-structfun-2"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-structfun-3"><span><code class="def-type">[<var class="var">A</var>, <var class="var">B</var>, …] =</code> <strong class="def-name">structfun</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-structfun-3"> ¶</a></span></dt>
<dd>
<p>Evaluate the function named <var class="var">name</var> on the fields of the structure
<var class="var">S</var>. The fields of <var class="var">S</var> are passed to the function <var class="var">fcn</var>
individually.
</p>
<p><code class="code">structfun</code> accepts an arbitrary function <var class="var">fcn</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 class="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>
<p>If the parameter <code class="code">"UniformOutput"</code> is set to true (the default), then
the function must return a single element which will be concatenated into
the return value. If <code class="code">"UniformOutput"</code> is false, the outputs are
placed into a structure with the same fieldnames as the input structure.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">s.name1 = "John Smith";
s.name2 = "Jill Jones";
structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s,
"UniformOutput", false)
⇒ scalar structure containing the fields:
name1 = Smith
name2 = Jones
</pre></div></div>
<p>Given the parameter <code class="code">"ErrorHandler"</code>, <var class="var">errfcn</var> defines a function
to call in case <var class="var">fcn</var> generates an error. The form of the function is
</p>
<div class="example">
<pre class="example-preformatted">function [...] = errfcn (<var class="var">se</var>, ...)
</pre></div>
<p>where there is an additional input argument to <var class="var">errfcn</var> relative to
<var class="var">fcn</var>, given by <var class="var">se</var>. This is a structure with the
elements <code class="code">"identifier"</code>, <code class="code">"message"</code> and <code class="code">"index"</code>,
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 class="pxref" href="#XREFcellfun"><code class="code">cellfun</code></a>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFcellfun">cellfun</a>, <a class="ref" href="#XREFarrayfun">arrayfun</a>, <a class="ref" href="#XREFspfun">spfun</a>.
</p></dd></dl>
<p>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
<code class="code">@plus</code> or define an anonymous function <code class="code">@(x,y) x + y</code>. But, the
anonymous function is 60% slower than the first method.
See <a class="xref" href="Operator-Overloading.html">Operator Overloading</a>, for a list of basic functions which might be used
in place of anonymous ones.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Accumulation.html">Accumulation</a>, Previous: <a href="Broadcasting.html">Broadcasting</a>, Up: <a href="Vectorization-and-Faster-Code-Execution.html">Vectorization and Faster Code Execution</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
