cellfun

Apply function to each cell in cell array

Syntax
[A1,...,Am] = cellfun(func,C1,...,Cn)
[A1,...,Am] = cellfun(func,C1,...,Cn,Name,Value)

Description
[A1,...,Am] = cellfun(func,C1,...,Cn) calls the function specified by function
handle func and passes elements from cell arrays C1,...,Cn, where n is the number of inputs to
function func. Output arrays A1,...,Am, where m is the number of outputs from function func,
contain the combined outputs from the function calls. The ith iteration corresponds to the
syntax [A1(i),...,Am(i)] = func(C1{i},...,Cn{i}). The cellfun function does not perform
the calls to function func in a specific order.
[A1,...,Am] = cellfun(func,C1,...,Cn,Name,Value) calls function func with additional
options specified by one or more Name,Value pair arguments. Possible values
for Nameare 'UniformOutput' or 'ErrorHandler'.

Input Arguments
func Handle to a function that accepts n input arguments and returns m output arguments.

If function func corresponds to more than one function file (that is, if func represents a set of overloaded functions),
of the input arguments.

Backward Compatibility
C1,...,Cn Cell arrays that contain the n inputs required for function func. Each cell array must have the same dimensions.
Name-Value Pair Arguments
Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name
and Value is the corresponding value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'UniformOutput' Logical value, as follows:

true Indicates that for all inputs, each output from function func is a scalar cell array, scalar structure, or a scalar v
(1) The cellfun function combines the outputs in arrays A1,...,Am, where m is the number of function outp
outputs.
false Requests that the cellfun function combine the outputs into cell arrays A1,...,Am. The outputs of functi
(0)

Default: true
'ErrorHandler' Handle to a function that catches any errors that occur when MATLAB attempts to execute function func. Define this
function func.

MATLAB calls the specified error-handling function with two input arguments:
A structure with these fields:
identifier Error identifier.

message Error message text.

 index Linear index corresponding to the element of the input cell array at the time of the error.
The set of input arguments to function func at the time of the error.

Output Arguments
A1,...,Am Arrays that collect the m outputs from function func. Each array A is the same size as each of the inputs C1,...,Cn

Function func can return output arguments of different classes. However, if UniformOutput is true (the default)
The individual outputs from function func must be scalar values (numeric, logical, or character), scalar structures, or
The class of a particular output argument must be the same for each set of inputs. The class of the corresponding outpu

Examples
Compute the mean of each vector in cell array C.
C = {1:10, [2; 4; 6], []};

averages = cellfun(@mean, C)

This code returns

averages =
5.5000 4.0000 NaN

Compute the size of each array in C, created in the previous example.

[nrows, ncols] = cellfun(@size, C)

This code returns

nrows =
1 3 0
ncols =
10 1 0

Create a cell array that contains character vectors, and abbreviate each of them to their first three
characters. Because the output character vectors are nonscalar, set UniformOutput to false.
days = {'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'};

abbrev = cellfun(@(x) x(1:3), days, 'UniformOutput', false)

The syntax @(x) creates an anonymous function. This code returns

abbrev =
'Mon' 'Tue' 'Wed' 'Thu' 'Fri'

Compute the covariance between arrays in two cell arrays C and D. Because the covariance output
is nonscalar, set UniformOutput to false.
c1 = rand(5,1); c2 = rand(10,1); c3 = rand(15,1);
 d1 = rand(5,1); d2 = rand(10,1); d3 = rand(15,1);
C = {c1, c2, c3};
D = {d1, d2, d3};

covCD = cellfun(@cov, C, D, 'UniformOutput', false)

This code returns

covCD =
[2x2 double] [2x2 double] [2x2 double]

Define and call a custom error handling function.

function result = errorfun(S, varargin)
warning(S.identifier, S.message);
result = NaN;
end

A = {rand(3)};
B = {rand(5)};
AgtB = cellfun(@(x,y) x > y, A, B, 'ErrorHandler', @errorfun, ...
'UniformOutput', false)

Extended Capabilities
Tall Arrays
Calculate with arrays that have more rows than fit in memory.

See Also
arrayfun | cell2mat | spfun | splitapply | structfun

Topics
Anonymous Functions
Create Function Handle
Introduced before R2006a

MATLAB Function Reference

cellfun
Apply a function to each element in a cell array
Syntax

D = cellfun('fname',C)
D = cellfun('size',C,k)
D = cellfun('isclass',C,classname)

Description

D = cellfun('fname',C) applies the function fname to the elements of the cell

array C and returns the results in the double array D. Each element of D contains the
value returned by fname for the corresponding element in C. The output array D 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

D = cellfun('size',C,k) returns the size along the k-th dimension of each element
of C.

D = cellfun('isclass',C,'classname') returns true for each element of C that

matches classname. This function syntax returns false for objects that are a subclass
of classname.

Limitations

If the cell array contains objects, cellfun does not call overloaded versions of the
function fname.

Example

Consider this 2-by-3 cell array:

C{1,1} = [1 2; 4 5];
 C{1,2} = 'Name';
C{1,3} = pi;
C{2,1} = 2 + 4i;
C{2,2} = 7;
C{2,3} = magic(3);

cellfun returns a 2-by-3 double array:

D = cellfun('isreal',C)

D =
1 1 1
0 1 1

len = cellfun('length',C)

len =
2 4 1
1 1 3

isdbl = cellfun('isclass',C,'double')

isdbl =
1 0 1
1 1 1

See Also

isempty, islogical, isreal, length, ndims, size

celldisp cellplot