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 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

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

Indicates that for all inputs, each output from function func is a scalar cell array, scalar structure, or a scalar value that is always of the same type and size. 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, or character), scalar structures, or scalar 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 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)

Related Examples

More About

collapse all

Tall Array Support

This function supports tall arrays with the limitations:

  • The input function must be a function handle.

  • The input function must not rely on any state, such as persistent variables or random number functions like rand.

  • The 'ErrorHandler' name-value pair is not supported.

  • With the 'UniformOutput' name-value pair, the outputs from the specified function must be numeric, logical, characters, or cell arrays.

For more information, see Tall Arrays.

See Also

| | | |

Introduced before R2006a

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support