Array functions

<arrayfun> - Apply a function to each element of an array.

ARRAYFUN Apply a function to each element of an array.

A = ARRAYFUN(FUN, B) applies the function specified by FUN to each

element of array B, and returns the results in array A. A is

the same size as B, and the (I,J,...)th element of A is equal to

FUN(B(I,J,...)). 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 inputs must be arrays of the

following types: numeric, logical, char, struct, cell. (Object arrays

are also supported, see Note 1). The order in which ARRAYFUN computes

elements of A is not specified and should not be relied on.

If FUN represents a set of overloaded functions, then ARRAYFUN follows

MATLAB dispatching rules in calling the function.

A = ARRAYFUN(FUN, B, C, ...) evaluates FUN using elements of arrays B,

C, ... as input arguments. The (I,J,...)th element of A is equal to

FUN(B(I,J,...), C(I,J,...), ...). B, C, ... must all have the same size.

[A, B, ...] = ARRAYFUN(FUN, C, ...), where FUN is a function handle to

a function that returns multiple outputs, returns arrays A, B, ...,

each corresponding to one of the output arguments of FUN. ARRAYFUN

calls FUN each time with as many outputs as there are in the call to

ARRAYFUN. FUN may return output arguments having different classes,

but the class of each output must be the same each time FUN is called.

[A, ...] = ARRAYFUN(FUN, B, ..., 'Param1', val1, ...) enables you to

specify optional parameter name/value pairs. Parameters are:

'UniformOutput' -- a logical value indicating whether or not the

output(s) of FUN can be returned without encapsulation in a cell

array. If true (the default), FUN must return scalar values that can

be concatenated into an array. If true, the outputs must be of the

following types: numeric, logical, char, struct, cell. If false,

ARRAYFUN returns a cell array (or multiple cell arrays), where the

(I,J,...)th cell contains the value FUN(B(I,J,...), ...). When

'UniformOutput' is false, the outputs can be of any type.

'ErrorHandler' -- a function handle, specifying the function

MATLAB is to call if the call to FUN fails. The error handling

function will be called with the following input arguments:

- a structure, with the fields: "identifier", "message", and

"index", respectively containing the identifier of the error

that occurred, the text of the error message, and the linear

index into the input array(s) at which the error occurred.

- the set of input arguments at which the call to the function

failed.

The error handling function should either rethrow an error, or

return the same number of outputs as FUN. These outputs are then

returned as the outputs of ARRAYFUN. If 'UniformOutput' is true,

the outputs of the error handler must also be scalars of the same

type as the outputs of FUN. Example:

function [A, B] = errorFunc(S, varargin)

warning(S.identifier, S.message); A = NaN; B = NaN;

If an error handler is not specified, the error from the call to

FUN will be rethrown.

NOTE 1:

If the input object arrays have either the subsref or size method

overloaded, then the following conditions have to be met for

ARRAYFUN to work as expected:

1) The size method must return an array of doubles as its output.

2) Linear indexing into the object array must be supported.

3) The product of the sizes returned from size must not exceed the

limit of the array, as defined by linearly indexing into the array.

Examples

Create a structure array with random matrices in the field f1.

s(1).f1 = rand(7,4) * 10;

s(2).f1 = rand(3,8) * 10;

s(3).f1 = rand(5,5) * 10;

Now compute the max and mean of each row of each matrix.

sMax = arrayfun(@(x)(max(x.f1)), s, 'UniformOutput', false)

sMax =

[1x4 double] [1x8 double] [1x5 double]

sMean = arrayfun(@(x)(mean(x.f1)), s, 'UniformOutput', false)

sMean =

[1x4 double] [1x8 double] [1x5 double]

See also cellfun, structfun, function_handle, cell2mat, spfun

Reference page in Help browser

doc arrayfun

<cellfun> - Apply a function to each cell of a cell array.

CELLFUN Apply a function to each cell of a cell array.

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

the array A. A is the same size as C, and the (I,J,...)th element of A

is equal to FUN(C{I,J,...}). 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 on.

If FUN represents a set of overloaded functions, then CELLFUN follows

MATLAB dispatching rules in calling the function.

A = CELLFUN(FUN, B, C, ...) evaluates FUN using the contents of the

cells of cell arrays B, C, ... as input arguments. The (I,J,...)th

element of A is equal to FUN(B{I,J,...}, C{I,J,...}, ...). B, C, ...

must all have the same size.

[A, B, ...] = CELLFUN(FUN, C, ...), where FUN is a function handle to a

function that returns multiple outputs, 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 may 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', val1, ...) enables you to

specify optional parameter name/value pairs. Parameters are:

'UniformOutput' -- a logical value indicating whether or not the

output(s) of FUN can be returned without encapsulation in a cell

array. If true (the default), FUN must return scalar values that can

be concatenated into an array. If true, the outputs must be of the

following types: numeric, logical, char, struct, cell. If false,

CELLFUN returns a cell array (or multiple cell arrays), where the

(I,J,...)th cell contains the value FUN(C{I,J,...}, ...). When

'UniformOutput' is false, the outputs can be of any type.

'ErrorHandler' -- a function handle, specifying the function

MATLAB is to call if the call to FUN fails. The error handling

function will be called with the following input arguments:

- a structure, with the fields: "identifier", "message", and

"index", respectively containing the identifier of the error

that occurred, the text of the error message, and the linear

index into the input array(s) at which the error occurred.

- the set of input arguments at which the call to the

function failed.

The error handling function should either rethrow an error, or

return the same number of outputs as FUN. These outputs are then

returned as the outputs of CELLFUN. If 'UniformOutput' is true,

the outputs of the error handler must also be scalars of the same

type as the outputs of FUN. Example:

function [A, B] = errorFunc(S, varargin)

warning(S.identifier, S.message); A = NaN; B = NaN;

If an error handler is not specified, the error from the call to

FUN is rethrown.

The following syntaxes are also accepted for backward compatibility:

A = CELLFUN('fun', C), where 'fun' is one of the following strings,

returns a logical or double array A the elements of which are computed

from those of C as follows:

'isreal' -- true for cells containing a real array, false

otherwise

'isempty' -- true for cells containing an empty array, false

otherwise

'islogical' -- true for cells containing a logical array, false

otherwise

'length' -- the length of the contents of each cell

'ndims' -- the number of dimensions of the contents of each cell

'prodofsize' -- the number of elements of the contents of each cell

A = CELLFUN('size', C, K) returns the size along the K-th dimension of

the contents of each cell of C.

A = CELLFUN('isclass', C, CLASSNAME) returns true for each cell of C

that contains an array of class CLASSNAME. Unlike the ISA function,

'isclass' of a subclass of CLASSNAME returns false.

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 and the size of several datasets.

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

Cmeans = cellfun(@mean, C);

[Cnrows,Cncols] = cellfun(@size, C);

Csize = cellfun(@size, C, 'UniformOutput', false);

% Find the positive values in several datasets.

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

Cpositives = cellfun(@(x) x(x>0), C, 'UniformOutput',false);

% Compute the covariance between several pairs of datasets.

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

See also arrayfun, structfun, function_handle, cell2mat, spfun

Overloaded methods:

codistributed/cellfun

Reference page in Help browser

doc cellfun

<structfun> - Apply a function to each field of a scalar structure.

STRUCTFUN Apply a function to each field of a scalar structure.

A = STRUCTFUN(FUN, B) applies the function specified by FUN to each

field of a scalar structure B, and returns the results in array A.

A is a column vector whose size is equal to the number of fields in B.

The Nth element of A is the result of applying FUN to the Nth field

of B, where the order of the fields is the same as that returned by

a call to FIELDNAMES. 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.

If FUN represents a set of overloaded functions, then STRUCTFUN follows

MATLAB dispatching rules in calling the function.

[A, B, ...] = STRUCTFUN(FUN, C), returns arrays A, B, ..., each

corresponding to one of the output arguments of FUN. STRUCTFUN

calls FUN each time with as many outputs as there are in the call to

STRUCTFUN. FUN may return output arguments having different classes,

but the class of each output must be the same each time FUN is called.

[A, ...] = STRUCTFUN(FUN, B, 'Param1', val1, ...) enables you to

specify optional parameter name/value pairs. Parameters are:

'UniformOutput' -- a logical value indicating whether or not the

output(s) of FUN can be returned without encapsulation in a

structure. If true (the default), FUN must return scalar values that

can be concatenated into an array. If true, the outputs must be of

the following types: numeric, logical, char, struct, cell. If

false, STRUCTFUN returns a scalar structure (or multiple scalar

structures), whose fields are the same as the fields of the input

structure B. The values in the output structure fields are the

results of calling FUN on the corresponding values in the input

structure B. When 'UniformOutput' is false, the outputs can be of

any type.

'ErrorHandler' -- a function handle, specifying the function

MATLAB is to call if the call to FUN fails. The error handling

function will be called with the following input arguments:

- a structure, with the fields: "identifier", "message", and

"index", respectively containing the identifier of the error

that occurred, the text of the error message, and the number of

the field (in the same order as returned by FIELDNAMES) at

which the error occurred.

- the input argument at which the call to the function failed.

The error handling function should either rethrow an error, or

return the same number of outputs as FUN. These outputs are then

returned as the outputs of STRUCTFUN. If 'UniformOutput' is true,

the outputs of the error handler must also be scalars of the same

type as the outputs of FUN. Example:

function [A, B] = errorFunc(S, varargin)

warning(S.identifier, S.message); A = NaN; B = NaN;