Navigation

Operators and Keywords

Function List:

C++ API

: cellfun (name, C)
: cellfun ("size", C, k)
: cellfun ("isclass", C, class)
: cellfun (func, C)
: cellfun (func, C, D)
: [a, …] = cellfun (…)
: cellfun (…, "ErrorHandler", errfunc)
: cellfun (…, "UniformOutput", val)

Evaluate the function named name on the elements of the cell array C.

Elements in C are passed on to the named function individually. The function name can be one of the functions

isempty

Return 1 for empty elements.

islogical

Return 1 for logical elements.

isnumeric

Return 1 for numeric elements.

isreal

Return 1 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 at each cell element.

size

Return the size along the k-th dimension.

isclass

Return 1 for elements of class.

Additionally, cellfun accepts an arbitrary function func in the form of an inline function, function handle, or the name of a function (in a character string). The function can take one or more arguments, with the inputs arguments given by C, D, etc. Equally the function can return one or more output 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. The outputs of the function 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 per default the output argument(s) are arrays of the same size as the input arguments. Input arguments that are singleton (1x1) cells will be automatically expanded to the size of the other 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 ("tolower", {"Foo", "Bar", "FooBar"},
        "UniformOutput", false)
⇒ {"foo", "bar", "foobar"}

Given the parameter "ErrorHandler", then errfunc defines a function to call in case func generates an error. The form of the function is 

function […] = errfunc (s, …)

where there is an additional input argument to errfunc relative to func, 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]

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: 

a = {…}
v = cellfun (@(x) det (x), a); # compute determinants
v = cellfun (@det, a); # faster

See also: arrayfun, structfun, spfun.

Package: octave