octave_packages/miscellaneous-1.1.0/apply.m

   1 ## Copyright (C) 2007, Muthiah Annamalai <muthiah.annamalai@mavs.uta.edu>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Loadable Function} {@var{return_value} =} apply (@var{@@function_handle},@var{cell_array_of_args})
  18 ## @deftypefnx {Loadable Function} {@var{return_value} =} apply (@var{@@function_handle})
  19 ## Apply calls the function @var{function_handle} with the arguments of the cell
  20 ## array @var{cell_array_of_args} which contains the actual arguments arg1,arg2,..., argn
  21 ## to the function, in that order. Apply invokes the function as
  22 ## @var{function_handle}(arg1, arg2, ... ,argn), where the arguments are
  23 ## extracted from each elements of the 1-row cell array @var{cell_array_of_args}.
  24 ##
  25 ## @emph{warning}: @code{apply} has been deprecated in favor of @code{arrayfun}
  26 ## and @code{cellfun} for arrays and cells respectively. This function will be
  27 ## removed from future versions of the 'miscellaneous' package".
  28 ##
  29 ## Apply also works on array of function handles if
  30 ## @var{function_handle} is passed as a cell array of a handles; in this
  31 ## case apply, evaluates each function (using the handle) with the same
  32 ## arguments.
  33 ##
  34 ## The cell-array argument is optional second argument, in the form
  35 ## of a 1-row with multiple elements. The elements of the cell-array
  36 ## form the actual arguments supplied when invoking the  function @var{function_handle}.
  37 ##
  38 ## The return value depends on the function invoked, and the validity of
  39 ## the arguments.
  40 ##
  41 ## @example
  42 ##   z=apply(@@sqrt,cell([1,2; 3,4]));
  43 ##   z=apply(@@apply,cell(@@sqrt,cell([1,2; 3,4])));
  44 ##   apply(@@sum,cell([1,2,3,4]))
  45 ##   apply(@@max,cell([1,2,3,4]))
  46 ##   apply(@@min,cell([1,2,3,4]))
  47 ## @end example
  48 ##
  49 ##
  50 ## In first case, apply computes the sqrt of the matrix [1,2; 3,4];
  51 ## The second example is meta-apply, using apply on itself.
  52 ## The rest of the examples invoke sum, max, min respectively.
  53 ## @end deftypefn
  54 ##
  55
  56 function rval=apply(fun_handle,cell_array)
  57
  58   persistent warned = false;
  59   if (! warned)
  60     warned = true;
  61     warning ("Octave:deprecated-function",
  62              "apply has been deprecated, and will be removed in the future. Use `arrayfun' or `cellfun' instead.");
  63   endif
  64
  65   if (nargin == 0)
  66     print_usage();
  67     error("apply(): needs at least 1 argument, see usage");
  68   elseif( nargin < 2)
  69     if iscell(fun_handle)
  70       for idx=1:length(fun_handle)
  71         rval(idx)=feval(@feval,fun_handle{idx});
  72       end
  73     else
  74       rval=feval(@feval,fun_handle);
  75     end
  76     return
  77   elseif(!iscell(cell_array))
  78     error("apply(): needs second argument, to be a cell-array");
  79   end
  80
  81
  82   if iscell(fun_handle)
  83     for idx=1:length(fun_handle)
  84       rval(idx)=feval(@feval,fun_handle{idx},cell_array{:});
  85     end
  86     return
  87   end
  88
  89   rval=feval(@feval,fun_handle,cell_array{:});
  90 end
  91 %!
  92 %!assert(apply({@min, @max, @mean},{[1:10]}),[ 1.0000 ,10.0000 ,5.5000])
  93 %!assert(apply(@min,{[1,2,3,4]}),1)
  94 %!assert(apply(@dot,{[1,2],[3,4]}),11)
  95 %!assert(apply(@min,{[1, 3]}),1)
  96 %!assert(apply(@sum,{[1:10]}),55)
  97 %!assert(apply(@sqrt,{[1,2; 3,4]}),sqrt([1,2;3,4]))
  98 %!assert(apply(@apply,{@sqrt,{[1,2; 3,4]}}),sqrt([1,2;3,4]))
  99 %!assert(apply(@sum,{[1,2,3,4]}),10)
 100 %!assert(apply(@max,{[1,2,3,4]}),4)
 101 %!assert(apply(@min,{[1,2,3,4]}),1)
 102 %!