Learn more about MATLAB

cellfun - Apply function to each cell in cell array

Syntax

A = cellfun(fun, C) A = cellfun(fun, C, D, ...) [A, B, ...] = cellfun(fun, C, ...) [A, ...] = cellfun(fun, C, ..., 'param1', value1, ...) A = cellfun('fname', C) A = cellfun('size', C, k) A = cellfun('isclass', C, 'classname')

Description

A = cellfun(fun, C) applies the function specified by fun to the contents of each cell of cell array C, and returns the results in array A. The value A returned by cellfun is the same size as C, and the (I,J,...)th element of A is equal to fun(C{I,J,...}). The first input argument fun is a function handle to a function that takes one input argument and returns a scalar value. fun must return values of the same class each time it is called. The order in which cellfun computes elements of A is not specified and should not be relied upon.

If fun is bound to more than one built-in or M-file (that is, if it represents a set of overloaded functions), then the class of the values that cellfun actually provides as input arguments to fun determines which functions are executed.

A = cellfun(fun, C, D, ...) evaluates fun using the contents of the cells of cell arrays C, D, ... as input arguments. The (I,J,...)th element of A is equal to fun(C{I,J,...}, D{I,J,...}, ...). All input arguments must be of the same size and shape.

[A, B, ...] = cellfun(fun, C, ...) evaluates fun, which is a function handle to a function that returns multiple outputs, and returns arrays A, B, ..., each corresponding to one of the output arguments of fun. cellfun calls fun each time with as many outputs as there are in the call to cellfun. fun can return output arguments having different classes, but the class of each output must be the same each time fun is called.

[A, ...] = cellfun(fun, C, ..., 'param1', value1, ...) enables you to specify optional parameter name and value pairs. Parameters recognized by cellfun are shown below. Enclose each parameter name with single quotes.

Parameter Name	Parameter Value
`UniformOutput`	Logical 1 (`true`) or 0 (`false`), indicating whether or not the outputs of `fun` can be returned without encapsulation in a cell array. See UniformOutput Parameter below.
`ErrorHandler`	Function handle, specifying the function that `cellfun` is to call if the call to `fun` fails. See ErrorHandler Parameter below.

UniformOutput Parameter

If you set the UniformOutput parameter to true (the default), fun must return scalar values that can be concatenated into an array. These values can also be a cell array.

If UniformOutput is false, cellfun returns a cell array (or multiple cell arrays), where the (I,J,...)th cell contains the value

fun(C{I,J,...}, ...)

ErrorHandler Parameter

The MATLAB software calls the function represented by the ErrorHandler parameter with two input arguments:

A structure having three fields, named identifier, message, and index, respectively containing the identifier of the error that occurred, the text of the error message, and a linear index into the input array or arrays for which the error occurred
The set of input arguments for which the call to the function failed

The error handling function must either rethrow the error that was caught, or it must return the output values from the call to fun. Error handling functions that do not rethrow the error must have the same number of outputs as fun. MATLAB places these output values in the output variables used in the call to arrayfun.

Shown here is an example of a simple error handling function, errorfun:

function [A, B] = errorfun(S, varargin)
warning(S.identifier, S.message);
A = NaN;  B = NaN;

If 'UniformOutput' is set to logical 1 (true), the outputs of the error handler must be scalars and of the same data type as the outputs of function fun.

If you do not specify an error handler, cellfun rethrows the error.

Backward Compatibility

The following syntaxes are also accepted for backward compatibility:

A = cellfun('fname', C) applies the function fname to the elements of cell array C and returns the results in the double array A. Each element of A contains the value returned by fname for the corresponding element in C. The output array A is the same size as the cell array C.

These functions are supported:

Function	Return Value
`isempty`	`true` for an empty cell element
`islogical`	`true` for a logical cell element
`isreal`	`true` for a real cell element
`length`	Length of the cell element
`ndims`	Number of dimensions of the cell element
`prodofsize`	Number of elements in the cell element

A = cellfun('size', C, k) returns the size along the kth dimension of each element of C.

A = cellfun('isclass', C, 'classname') returns logical 1 (true) for each element of C that matches classname. This function syntax returns logical 0 (false) for objects that are a subclass of classname.

Note For the previous three syntaxes, if C contains objects, cellfun does not call any overloaded versions of MATLAB functions corresponding to the above strings.

Examples

Compute the mean of several data sets:

C = {1:10, [2; 4; 6], []};

Cmeans = cellfun(@mean, C)
Cmeans =
    5.5000    4.0000       NaN

Compute the size of these data sets:

[Cnrows, Cncols] = cellfun(@size, C)
Cnrows =
     1     3     0
Cncols =
    10     1     0

Again compute the size, but with UniformOutput set to false:

Csize = cellfun(@size, C, 'UniformOutput', false)
Csize = 
    [1x2 double]    [1x2 double]    [1x2 double]

Csize{:}
ans =
     1    10
ans =
     3     1
ans =
     0     0

Find the positive values in several data sets.

C = {randn(10,1), randn(20,1), randn(30,1)};

Cpositives = cellfun(@(x) x(x>0), C, 'UniformOutput',false)
Cpositives = 
    [6x1 double]    [11x1 double]    [15x1 double]

Cpositives{:}
ans =
    0.1253
    0.2877
    1.1909
     etc.
ans =
    0.7258
    2.1832
    0.1139
     etc.
ans =
    0.6900
    0.8156
    0.7119
     etc.

Compute the covariance between several pairs of data sets:

C = {randn(10,1), randn(20,1), randn(30,1)};
D = {randn(10,1), randn(20,1), randn(30,1)};

CDcovs = cellfun(@cov, C, D, 'UniformOutput', false)
CDcovs = 
    [2x2 double]    [2x2 double]    [2x2 double]

CDcovs{:}
ans =
    0.7353   -0.2148
   -0.2148    0.6080
ans =
    0.5743   -0.2912
   -0.2912    0.8505
ans =
    0.7130    0.1750
    0.1750    0.6910