### 19.3 Function Application ¶

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.

`B =` arrayfun `(fcn, A)` ¶
`B =` arrayfun `(fcn, A1, A2, …)` ¶
`[B1, B2, …] =` arrayfun `(fcn, A, …)` ¶
`B =` arrayfun `(…, "UniformOutput", val)` ¶
`B =` arrayfun `(…, "ErrorHandler", errfcn)` ¶

  Execute a function on each element of an array.

  This is useful for functions that do not accept array arguments. If the function does accept array arguments it is better to call the function directly.

  The first input argument fcn can be a string, a function handle, an inline function, or an anonymous function. The input argument A can be a logical array, a numeric array, a string array, a structure array, or a cell array. `arrayfun` passes all elements of A individually to the function fcn and collects the results. The equivalent pseudo-code is

      cls = class (fcn (A(1));
      B = zeros (size (A), cls);
      for i = 1:numel (A)
        B(i) = fcn (A(i))
      endfor

  The named function can also take more than two input arguments, with the input arguments given as third input argument A2, fourth input argument A2, ... If given more than one array input argument then all input arguments must have the same sizes. For example:

      arrayfun (@atan2, [1, 0], [0, 1])
           ⇒ [ 1.57080   0.00000 ]

  If the parameter val after a further string input argument `"UniformOutput"` is set `true` (the default), then the named function fcn 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 `false`, then the outputs are concatenated in a cell array. For example:

      arrayfun (@(x,y) x:y, "abc", "def", "UniformOutput", false)
      ⇒
         {
           [1,1] = abcd
           [1,2] = bcde
           [1,3] = cdef
         }

  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:

      [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)
      }

  If the parameter errfcn after a further string input argument `"ErrorHandler"` is another string, a function handle, an inline function, or an anonymous function, then errfcn defines a function to call in the case that fcn generates an error. The definition of the function must be of the form

      function [...] = errfcn (s, ...)

  where there is an additional input argument to errfcn relative to fcn, given by s. This is a structure with the elements `"identifier"`, `"message"`, and `"index"` 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 errfcn must have the same size as the output argument of fcn, otherwise a real error is thrown. For example:

      function y = ferr (s, x), y = "MyString"; endfunction
      arrayfun (@str2num, [1234],
                "UniformOutput", false, "ErrorHandler", @ferr)
      ⇒
         {
           [1,1] = MyString
         }

  See also: spfun, cellfun, structfun.

`y =` spfun `(f, S)` ¶

  Compute `f (S)` for the nonzero elements of S.

  The input function f is applied only to the nonzero elements of the input matrix S which is typically sparse. The function f can be passed as a string, function handle, or inline function.

  The output y is a sparse matrix with the same sparsity structure as the input S. `spfun` preserves sparsity structure which is different than simply applying the function f to the sparse matrix S when `f (0) != 0`.

  Example

  Sparsity preserving `spfun` versus normal function application

      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

      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

  See also: arrayfun, cellfun, structfun.

`A =` cellfun `(@fcn, C)` ¶
`A =` cellfun `("fcn", C)` ¶
`A =` cellfun `(fcn, C)` ¶
`A =` cellfun `(fcn, C1, C2, …)` ¶
`[A1, A2, …] =` cellfun `(…)` ¶
`A =` cellfun `(…, "UniformOutput", val)` ¶
`A =` cellfun `(…, "ErrorHandler", errfcn)` ¶
`A =` cellfun `('isempty', C)` ¶
`A =` cellfun `('islogical', C)` ¶
`A =` cellfun `('isnumeric', C)` ¶
`A =` cellfun `('isreal', C)` ¶
`A =` cellfun `('length', C)` ¶
`A =` cellfun `('numel', C)` ¶
`A =` cellfun `('prodofsize', C)` ¶
`A =` cellfun `('size', C, dim)` ¶
`A =` cellfun `('isclass', C, class)` ¶

  Evaluate the function fcn on the elements of the cell array C.

  `cellfun` accepts an arbitrary function fcn given as a name in a character string, as a function handle, or as an inline function. Specifying fcn with a character string is preferred as the performance is ~3X better for builtin functions and equivalent for m-files.

  `cellfun` 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—`cellfun ('fcn'), C)`—without options is supported. If you need access to an overloaded version of a function, such as `numel` for a particular `classdef` file, then you cannot use the accelerated function name and must use a function handle instead, e.g., `@numel`.

  The high-performance functions are

  `'isempty'`

    Return true for empty elements.

  `'islogical'`

    Return true for logical elements.

  `'isnumeric'`

    Return true for numeric elements.

  `'isreal'`

    Return true for real elements.

  `'length'`

    Return a vector of the lengths of cell elements.

  `'ndims'`

    Return the number of dimensions of each element.

  `'numel'`
  `'prodofsize'`

    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.

  `'size'`

    Return the size along dimension dim.

  `'isclass'`

    Return true for elements which are of type class.

  Elements in C 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 C1, C2, etc. Input arguments that are singleton (1x1) cells will be automatically expanded to the size of the other arguments. For example:

      cellfun ("atan2", {1, 0}, {0, 1})
           ⇒ [ 1.57080   0.00000 ]

  The number of output arguments of `cellfun` 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 `cellfun` like this:

      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

  Note that, by default, the output argument(s) are arrays of the same size as the input arguments.

  If the parameter `"UniformOutput"` is set to true (the default), then the function must return scalars which will be concatenated into the return array(s). If `"UniformOutput"` is false, the outputs are concatenated into a cell array (or cell arrays). For example:

      cellfun ("lower", {"Foo", "Bar", "FooBar"},
               "UniformOutput", false)
      ⇒ {"foo", "bar", "foobar"}

  The parameter `"ErrorHandler"` specifies a function errfcn to call if fcn generates an error. The form of the function is

      function [...] = errfcn (s, ...)

  where there is an additional input argument to errfcn relative to fcn, given by s. This is a structure with the elements `"identifier"`, `"message"`, and `"index"` giving respectively the error identifier, the error message, and the index into the input arguments of the element that caused the error. For example:

      function y = foo (s, x), y = NaN; endfunction
      cellfun ("factorial", {-1,2}, "ErrorHandler", @foo)
      ⇒ [NaN 2]

  Programming Note: Use `cellfun` intelligently. The `cellfun` 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:

      C = {...}
      v = cellfun (@(x) det (x), C); # compute determinants
      v = cellfun (@det, C);         # 40% faster

  See also: arrayfun, structfun, spfun.

`A =` structfun `(fcn, S)` ¶
`A =` structfun `(…, "ErrorHandler", errfcn)` ¶
`A =` structfun `(…, "UniformOutput", val)` ¶
`[A, B, …] =` structfun `(…)` ¶

  Evaluate the function named name on the fields of the structure S. The fields of S are passed to the function fcn individually.

  `structfun` accepts an arbitrary function 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 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 `"UniformOutput"` is set to true (the default), then the function must return a single element which will be concatenated into the return value. If `"UniformOutput"` is false, the outputs are placed into a structure with the same fieldnames as the input structure.

      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

  Given the parameter `"ErrorHandler"`, errfcn defines a function to call in case fcn generates an error. The form of the function is

      function [...] = errfcn (se, ...)

  where there is an additional input argument to errfcn relative to fcn, given by se. This is a structure with the elements `"identifier"`, `"message"` and `"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, see `cellfun`.

  See also: cellfun, arrayfun, spfun.

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 `@plus` or define an anonymous function `@(x,y) x + y`. But, the anonymous function is 60% slower than the first method. See Operator Overloading, for a list of basic functions which might be used in place of anonymous ones.