Mercurial > octave
annotate scripts/general/structfun.m @ 29359:7854d5752dd2
maint: merge stable to default.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Wed, 10 Feb 2021 10:10:40 -0500 |
parents | 5394d688d456 0a5b15007766 |
children | 796f54d4ddbf |
rev | line source |
---|---|
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
1 ######################################################################## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
2 ## |
29358
0a5b15007766
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
27923
diff
changeset
|
3 ## Copyright (C) 2007-2021 The Octave Project Developers |
27918
b442ec6dda5c
use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents:
26600
diff
changeset
|
4 ## |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
5 ## See the file COPYRIGHT.md in the top-level directory of this |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
6 ## distribution or <https://octave.org/copyright/>. |
6863 | 7 ## |
8 ## This file is part of Octave. | |
9 ## | |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
10 ## Octave is free software: you can redistribute it and/or modify it |
6863 | 11 ## under the terms of the GNU General Public License as published by |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
12 ## the Free Software Foundation, either version 3 of the License, or |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22627
diff
changeset
|
13 ## (at your option) any later version. |
6863 | 14 ## |
15 ## Octave is distributed in the hope that it will be useful, but | |
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of | |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22627
diff
changeset
|
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22627
diff
changeset
|
18 ## GNU General Public License for more details. |
6863 | 19 ## |
20 ## You should have received a copy of the GNU General Public License | |
7016 | 21 ## along with Octave; see the file COPYING. If not, see |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
22 ## <https://www.gnu.org/licenses/>. |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
23 ## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
24 ######################################################################## |
6863 | 25 |
26 ## -*- texinfo -*- | |
20852
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
27 ## @deftypefn {} {} structfun (@var{func}, @var{S}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
28 ## @deftypefnx {} {[@var{A}, @dots{}] =} structfun (@dots{}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
29 ## @deftypefnx {} {} structfun (@dots{}, "ErrorHandler", @var{errfunc}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
30 ## @deftypefnx {} {} structfun (@dots{}, "UniformOutput", @var{val}) |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
31 ## |
6863 | 32 ## Evaluate the function named @var{name} on the fields of the structure |
11469
c776f063fefe
Overhaul m-script files to use common variable name between code and documentation.
Rik <octave@nomad.inbox5.com>
parents:
11190
diff
changeset
|
33 ## @var{S}. The fields of @var{S} are passed to the function @var{func} |
6863 | 34 ## individually. |
35 ## | |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
36 ## @code{structfun} accepts an arbitrary function @var{func} in the form of an |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
37 ## inline function, function handle, or the name of a function (in a character |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
38 ## string). In the case of a character string argument, the function must |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
39 ## accept a single argument named @var{x}, and it must return a string value. |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
40 ## If the function returns more than one argument, they are returned as |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
41 ## separate output variables. |
6863 | 42 ## |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
43 ## If the parameter @qcode{"UniformOutput"} is set to true (the default), then |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
44 ## the function must return a single element which will be concatenated into |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
45 ## the return value. If @qcode{"UniformOutput"} is false, the outputs are |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
46 ## placed into a structure with the same fieldnames as the input structure. |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
47 ## |
6863 | 48 ## @example |
49 ## @group | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
50 ## s.name1 = "John Smith"; |
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
51 ## s.name2 = "Jill Jones"; |
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
52 ## structfun (@@(x) regexp (x, '(\w+)$', "matches")@{1@}, s, |
8507 | 53 ## "UniformOutput", false) |
26600
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
54 ## @result{} scalar structure containing the fields: |
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
55 ## name1 = Smith |
f6730533820e
doc: clean up doc example blocks for accuracy and consistent formatting
Mike Miller <mtmiller@octave.org>
parents:
26376
diff
changeset
|
56 ## name2 = Jones |
6863 | 57 ## @end group |
58 ## @end example | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
59 ## |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
60 ## Given the parameter @qcode{"ErrorHandler"}, @var{errfunc} defines a function |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
61 ## to call in case @var{func} generates an error. The form of the function is |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
62 ## |
6863 | 63 ## @example |
64 ## function [@dots{}] = errfunc (@var{se}, @dots{}) | |
65 ## @end example | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
66 ## |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10793
diff
changeset
|
67 ## @noindent |
6863 | 68 ## where there is an additional input argument to @var{errfunc} relative to |
16826
a4969508008e
doc: Periodic spellcheck of the documentation.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
69 ## @var{func}, given by @nospell{@var{se}}. This is a structure with the |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
70 ## elements @qcode{"identifier"}, @qcode{"message"} and @qcode{"index"}, |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
71 ## giving respectively the error identifier, the error message, and the index |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
72 ## into the input arguments of the element that caused the error. For an |
28959
5394d688d456
doc: Use @code{} within alternate text for @xref,@pxref macros for better Info display.
Rik <rik@octave.org>
parents:
27923
diff
changeset
|
73 ## example on how to use an error handler, @pxref{XREFcellfun,,@code{cellfun}}. |
10122
9d1a14e12431
Update docs and add tests for container functions
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
9036
diff
changeset
|
74 ## |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
10549
diff
changeset
|
75 ## @seealso{cellfun, arrayfun, spfun} |
6863 | 76 ## @end deftypefn |
77 | |
22767
212333a97d8d
maint: Remove dangling ';' from m-file function declarations.
Rik <rik@octave.org>
parents:
22755
diff
changeset
|
78 function varargout = structfun (func, S, varargin) |
10134
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
79 |
6863 | 80 if (nargin < 2) |
81 print_usage (); | |
82 endif | |
83 | |
10134
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
84 nargs = length (varargin); |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
85 |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
86 recognized_opts = {"UniformOutput", "ErrorHandler"}; |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
87 uo_str = recognized_opts{1}; |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
88 |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
89 uniform_output = true; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
90 |
10134
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
91 while (nargs >= 2) |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
92 opt_match = strcmpi (varargin{nargs-1}, recognized_opts); |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
93 if (opt_match(1)) |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
94 uniform_output = varargin{nargs}; |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
95 endif |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
96 if (any (opt_match)) |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
97 nargs -= 2; |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
98 else |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
99 break; |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
100 endif |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
101 endwhile |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
102 |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
103 if (nargs > 0) |
be13fa20656a
error on invalid opts in structfun
Jaroslav Hajek <highegg@gmail.com>
parents:
10132
diff
changeset
|
104 error ("structfun: invalid options"); |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
105 endif |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
106 |
6863 | 107 varargout = cell (max ([nargout, 1]), 1); |
11469
c776f063fefe
Overhaul m-script files to use common variable name between code and documentation.
Rik <octave@nomad.inbox5.com>
parents:
11190
diff
changeset
|
108 [varargout{:}] = cellfun (func, struct2cell (S), varargin{:}); |
6863 | 109 |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
110 if (! uniform_output) |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
111 varargout = cellfun ("cell2struct", varargout, {fieldnames(S)}, {1}, ... |
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
112 uo_str, false); |
6863 | 113 endif |
21758
ffad2baa90f7
maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
114 |
6863 | 115 endfunction |
116 | |
117 | |
118 %!test | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
119 %! s.name1 = "John Smith"; |
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
120 %! s.name2 = "Jill Jones"; |
6863 | 121 %! l.name1 = "Smith"; |
122 %! l.name2 = "Jones"; | |
11587
c792872f8942
all script files: untabify and strip trailing whitespace
John W. Eaton <jwe@octave.org>
parents:
11523
diff
changeset
|
123 %! o = structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s, |
10549 | 124 %! "UniformOutput", false); |
6863 | 125 %! assert (o, l); |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
126 |
13305
63463570d9fe
Add %!endfunction block keyword to test.m
Rik <octave@nomad.inbox5.com>
parents:
12931
diff
changeset
|
127 %!function [a, b] = __twoouts (x) |
22627
7b190a2f11cb
maint: Use 2-space indent in definition of BIST %!functions.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
128 %! a = x + x; |
7b190a2f11cb
maint: Use 2-space indent in definition of BIST %!functions.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
129 %! b = x * x; |
13305
63463570d9fe
Add %!endfunction block keyword to test.m
Rik <octave@nomad.inbox5.com>
parents:
12931
diff
changeset
|
130 %!endfunction |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
131 |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
132 %!test |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
133 %! s = struct ("a", {1, 2, 3}, "b", {4, 5, 6}); |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
134 %! c(1:2, 1, 1) = [2; 8]; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
135 %! c(1:2, 1, 2) = [4; 10]; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
136 %! c(1:2, 1, 3) = [6; 12]; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
137 %! d(1:2, 1, 1) = [1; 16]; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
138 %! d(1:2, 1, 2) = [4; 25]; |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
139 %! d(1:2, 1, 3) = [9; 36]; |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
140 %! [aa, bb] = structfun (@__twoouts, s); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
141 %! assert (aa, c); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
142 %! assert (bb, d); |
10132
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
143 |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
144 %!test |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
145 %! s = struct ("a", {1, 2, 3}, "b", {4, 5, 6}); |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
146 %! c = struct ("a", {2, 4, 6}, "b", {8, 10, 12}); |
aa0f575cf39b
improve structfun's Matlab compatibility
Jaroslav Hajek <highegg@gmail.com>
parents:
10122
diff
changeset
|
147 %! d = struct ("a", {1, 4, 9}, "b", {16, 25, 36}); |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
148 %! [aa, bb] = structfun (@__twoouts, s, "UniformOutput", false); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
149 %! assert (aa, c); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14327
diff
changeset
|
150 %! assert (bb, d); |