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(C{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 Name are '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), MATLAB determines which function to call based on the class of the input arguments. 

 Backward Compatibility 

cellfun accepts function name strings for function func, rather than a function handle, for these function names: isempty, islogical, isreal, length, ndims, prodofsize, size, isclass. Enclose the function name in single quotes.

If you specify a function name string rather than a function handle:

cellfun does not call any overloaded versions of the function.

The size and isclass functions require additional inputs to the cellfun function:

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 the classname string. This syntax returns logical 0 (false) for objects that are a subclass of classname. 

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, where 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 (1)

Indicates that for all inputs, each output from function func is a cell array or a scalar value that is always of the same type. The cellfun function combines the outputs in arrays A1,...,Am, where m is the number of function outputs. Each output array is of the same type as the individual function outputs.

false (0)

Requests that the cellfun function combine the outputs into cell arrays A1,...,Am. The outputs of function func can be of any size or type.

Default: true

'ErrorHandler'

Handle to a function that catches any errors that occur when MATLAB attempts to execute function func. Define this function so that it rethrows the error or returns valid outputs for 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, character, or structure) or cell arrays.

The class of a particular output argument must be the same for each set of inputs. The class of the corresponding output array is the same as the class of the outputs from function func.

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 strings, and abbreviate those strings to the first three characters. Because the output strings 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)