Mercurial > octave
view scripts/general/structfun.m @ 31221:f5755dbacd8d
maint: merge stable to default
author | Pantxo Diribarne <pantxo.diribarne@gmail.com> |
---|---|
date | Wed, 31 Aug 2022 22:04:02 +0200 |
parents | e1788b1a315f |
children | 597f3ee61a48 |
line wrap: on
line source
######################################################################## ## ## Copyright (C) 2007-2022 The Octave Project Developers ## ## See the file COPYRIGHT.md in the top-level directory of this ## distribution or <https://octave.org/copyright/>. ## ## This file is part of Octave. ## ## Octave is free software: you can redistribute it and/or modify it ## under the terms of the GNU General Public License as published by ## the Free Software Foundation, either version 3 of the License, or ## (at your option) any later version. ## ## Octave is distributed in the hope that it will be useful, but ## WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with Octave; see the file COPYING. If not, see ## <https://www.gnu.org/licenses/>. ## ######################################################################## ## -*- texinfo -*- ## @deftypefn {} {@var{A} =} structfun (@var{fcn}, @var{S}) ## @deftypefnx {} {@var{A} =} structfun (@dots{}, "ErrorHandler", @var{errfcn}) ## @deftypefnx {} {@var{A} =} structfun (@dots{}, "UniformOutput", @var{val}) ## @deftypefnx {} {[@var{A}, @var{B}, @dots{}] =} structfun (@dots{}) ## ## Evaluate the function named @var{name} on the fields of the structure ## @var{S}. The fields of @var{S} are passed to the function @var{fcn} ## individually. ## ## @code{structfun} accepts an arbitrary function @var{fcn} 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}, 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 @qcode{"UniformOutput"} is set to true (the default), then ## the function must return a single element which will be concatenated into ## the return value. If @qcode{"UniformOutput"} is false, the outputs are ## placed into a structure with the same fieldnames as the input structure. ## ## @example ## @group ## s.name1 = "John Smith"; ## s.name2 = "Jill Jones"; ## structfun (@@(x) regexp (x, '(\w+)$', "matches")@{1@}, s, ## "UniformOutput", false) ## @result{} scalar structure containing the fields: ## name1 = Smith ## name2 = Jones ## @end group ## @end example ## ## Given the parameter @qcode{"ErrorHandler"}, @var{errfcn} defines a function ## to call in case @var{fcn} generates an error. The form of the function is ## ## @example ## function [@dots{}] = errfcn (@var{se}, @dots{}) ## @end example ## ## @noindent ## where there is an additional input argument to @var{errfcn} relative to ## @var{fcn}, given by @nospell{@var{se}}. This is a structure with the ## elements @qcode{"identifier"}, @qcode{"message"} and @qcode{"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, @pxref{XREFcellfun,,@code{cellfun}}. ## ## @seealso{cellfun, arrayfun, spfun} ## @end deftypefn function varargout = structfun (fcn, S, varargin) if (nargin < 2) print_usage (); endif nargs = length (varargin); recognized_opts = {"UniformOutput", "ErrorHandler"}; uo_str = recognized_opts{1}; uniform_output = true; while (nargs >= 2) opt_match = strcmpi (varargin{nargs-1}, recognized_opts); if (opt_match(1)) uniform_output = varargin{nargs}; endif if (any (opt_match)) nargs -= 2; else break; endif endwhile if (nargs > 0) error ("structfun: invalid options"); endif varargout = cell (max ([nargout, 1]), 1); [varargout{:}] = cellfun (fcn, struct2cell (S), varargin{:}); if (! uniform_output) varargout = cellfun ("cell2struct", varargout, {fieldnames(S)}, {1}, ... uo_str, false); endif endfunction %!test %! s.name1 = "John Smith"; %! s.name2 = "Jill Jones"; %! l.name1 = "Smith"; %! l.name2 = "Jones"; %! o = structfun (@(x) regexp (x, '(\w+)$', "matches"){1}, s, %! "UniformOutput", false); %! assert (o, l); %!function [a, b] = __twoouts (x) %! a = x + x; %! b = x * x; %!endfunction %!test %! s = struct ("a", {1, 2, 3}, "b", {4, 5, 6}); %! c(1:2, 1, 1) = [2; 8]; %! c(1:2, 1, 2) = [4; 10]; %! c(1:2, 1, 3) = [6; 12]; %! d(1:2, 1, 1) = [1; 16]; %! d(1:2, 1, 2) = [4; 25]; %! d(1:2, 1, 3) = [9; 36]; %! [aa, bb] = structfun (@__twoouts, s); %! assert (aa, c); %! assert (bb, d); %!test %! s = struct ("a", {1, 2, 3}, "b", {4, 5, 6}); %! c = struct ("a", {2, 4, 6}, "b", {8, 10, 12}); %! d = struct ("a", {1, 4, 9}, "b", {16, 25, 36}); %! [aa, bb] = structfun (@__twoouts, s, "UniformOutput", false); %! assert (aa, c); %! assert (bb, d);