Mercurial > octave

annotate scripts/miscellaneous/nthargout.m @ 27919:1891570abac8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update Octave Project Developers copyright for the new year In files that have the "Octave Project Developers" copyright notice, update for 2020.
author John W. Eaton <jwe@octave.org>
date Mon, 06 Jan 2020 22:29:51 -0500
parents b442ec6dda5c
children bd51beb6205e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27919
1891570abac8 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 27918
diff changeset
1 ## Copyright (C) 2012-2020 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
2 ##
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
3 ## See the file COPYRIGHT.md in the top-level directory of this distribution
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ## or <https://octave.org/COPYRIGHT.html/>.
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
5 ##
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
6 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
7 ## This file is part of Octave.
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
8 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 24491
diff changeset
9 ## Octave is free software: you can redistribute it and/or modify it
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
10 ## 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: 24491
diff changeset
11 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
12 ## (at your option) any later version.
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
13 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
14 ## Octave is distributed in the hope that it will be useful, but
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
15 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
16 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## GNU General Public License for more details.
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
18 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
19 ## You should have received a copy of the GNU General Public License
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
20 ## 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: 24491
diff changeset
21 ## <https://www.gnu.org/licenses/>.
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
22
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
23 ## -*- texinfo -*-
20852
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20158
diff changeset
24 ## @deftypefn {} {} nthargout (@var{n}, @var{func}, @dots{})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20158
diff changeset
25 ## @deftypefnx {} {} nthargout (@var{n}, @var{ntot}, @var{func}, @dots{})
20158
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
26 ## Return the @var{n}th output argument of the function specified by the
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
27 ## function handle or string @var{func}.
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
28 ##
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
29 ## Any additional arguments are passed directly to @var{func}. The total
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
30 ## number of arguments to call @var{func} with can be passed in @var{ntot}; by
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
31 ## default @var{ntot} is @var{n}. The input @var{n} can also be a vector of
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
32 ## indices of the output, in which case the output will be a cell array of the
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
33 ## requested output arguments.
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
34 ##
20158
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
35 ## The intended use @code{nthargout} is to avoid intermediate variables. For
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
36 ## example, when finding the indices of the maximum entry of a matrix, the
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
37 ## following two compositions of nthargout
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
38 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
39 ## @example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
40 ## @group
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
41 ## @var{m} = magic (5);
14868
5d3a684236b0 maint: Use Octave coding conventions for cuddling parentheses in scripts directory
Rik <octave@nomad.inbox5.com>
parents: 14363
diff changeset
42 ## cell2mat (nthargout ([1, 2], @@ind2sub, size (@var{m}),
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
43 ## nthargout (2, @@max, @var{m}(:))))
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
44 ## @result{} 5 3
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
45 ## @end group
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
46 ## @end example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
47 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
48 ## @noindent
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
49 ## are completely equivalent to the following lines:
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
50 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
51 ## @example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
52 ## @group
14868
5d3a684236b0 maint: Use Octave coding conventions for cuddling parentheses in scripts directory
Rik <octave@nomad.inbox5.com>
parents: 14363
diff changeset
53 ## @var{m} = magic (5);
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
54 ## [~, idx] = max (@var{M}(:));
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
55 ## [i, j] = ind2sub (size (@var{m}), idx);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
56 ## [i, j]
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
57 ## @result{} 5 3
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
58 ## @end group
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
59 ## @end example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
60 ##
20158
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
61 ## It can also be helpful to have all output arguments in a single cell in the
7503499a252b doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19697
diff changeset
62 ## following manner:
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
63 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
64 ## @example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
65 ## @var{USV} = nthargout ([1:3], @@svd, hilb (5));
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
66 ## @end example
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
67 ##
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
68 ## @seealso{nargin, nargout, varargin, varargout, isargout}
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
69 ## @end deftypefn
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
70
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
71 ## Author: Jordi Gutiérrez Hermoso
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
72
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
73 function out = nthargout (n, varargin)
21758
ffad2baa90f7 maint: Use newlines to make code more readable.
Rik <rik@octave.org>
parents: 20852
diff changeset
74
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
75 if (nargin < 2)
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
76 print_usage ();
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
77 endif
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
78
25803
23483673ba43 Use is_function_handle instead of isa (x, "function_handle").
Rik <rik@octave.org>
parents: 25054
diff changeset
79 if (is_function_handle (varargin{1}) || ischar (varargin{1}))
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
80 ntot = max (n(:));
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
81 func = varargin{1};
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
82 args = varargin(2:end);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
83 elseif (isnumeric (varargin{1})
25803
23483673ba43 Use is_function_handle instead of isa (x, "function_handle").
Rik <rik@octave.org>
parents: 25054
diff changeset
84 && (is_function_handle (varargin{2}) || ischar (varargin{2})))
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
85 ntot = varargin{1};
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
86 func = varargin{2};
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
87 args = varargin(3:end);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
88 else
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
89 print_usage ();
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
90 endif
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
91
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
92 if (any (n != fix (n)) || ntot != fix (ntot) || any (n <= 0) || ntot <= 0)
15202
f3b5cadfd6d5 fix missing semicolons in various .m files
John W. Eaton <jwe@octave.org>
parents: 14868
diff changeset
93 error ("nthargout: N and NTOT must consist of positive integers");
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
94 endif
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
95
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
96 outargs = cell (1, ntot);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
97
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
98 try
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
99 [outargs{:}] = feval (func, args{:});
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
100 if (numel (n) > 1)
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
101 out = outargs(n);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
102 else
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
103 out = outargs{n};
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
104 endif
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
105 catch
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
106 err = lasterr ();
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
107 if (strfind ("some elements undefined in return list", err))
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
108 error ("nthargout: Too many output arguments: %d", ntot);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
109 else
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
110 error (err);
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
111 endif
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
112 end_try_catch
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
113
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
114 endfunction
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
115
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
116
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
117 %!shared m
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
118 %! m = magic (5);
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14138
diff changeset
119 %!assert (nthargout ([1,2], @ind2sub, size (m), nthargout (2, @max, m(:))), {5,3})
13749
62d1f56b0be7 New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
diff changeset
120 %!assert (nthargout (3, @find, m(m>20)), [23, 24, 25, 21, 22]')