arrayfun

Apply function to each element of array

collapse all in page

Syntax

[B1,...,Bm] = arrayfun(func,A1,...,An)
[B1,...,Bm] = arrayfun(func,A1,...,An,Name,Value)

Description

[B1,...,Bm] = arrayfun(func,A1,...,An) calls the function specified by function handle func and passes elements from arrays A1,...,An, where n is the number of inputs to function func. Output arrays B1,...,Bm, 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 [B1(i),...,Bm(i)] = func(A1(i),...,An(i)). The arrayfun function does not perform the calls to function func in a specific order.

[B1,...,Bm] = arrayfun(func,A1,...,An,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.

A1,...,An

Arrays that contain the n inputs required for function func. Each array must have the same dimensions. Arrays can be numeric, character, logical, cell, structure, or user-defined object arrays.

If any input A is a user-defined object array, and you overloaded the subsref or size methods, arrayfun requires that:

  • The size method returns an array of type double.

  • The object array supports linear indexing.

  • The product of the sizes returned by the size method does not exceed the limit of the array, as defined by linear indexing into the array.

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 scalar value that is always of the same type and size. The arrayfun function combines the outputs in arrays B1,...,Bm, 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 arrayfun function combine the outputs into cell arrays B1,...,Bm. 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

B1,...,Bm

Arrays that collect the m outputs from function func. Each array B is the same size as each of the inputs A1,...,An.

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

To run the examples in this section, create a nonscalar structure array with arrays of different sizes in field f1.

s(1).f1 = rand(3, 6);
s(2).f1 = magic(12);
s(3).f1 = ones(5, 10);

Count the number of elements in each f1 field.

counts = arrayfun(@(x) numel(x.f1), s)

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

counts =
    18   144    50

Compute the size of each array in the f1 fields.

[nrows, ncols] = arrayfun(@(x) size(x.f1), s)

This code returns

nrows =
     3    12     5
ncols =
     6    12    10

Compute the mean of each column in the f1 fields of s. Because the output is nonscalar, set UniformOutput to false.

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

This code returns

averages = 
    [1x6 double]    [1x12 double]    [1x10 double]

Create additional nonscalar structures t and u, and test for equality between the arrays in fields f1 across structures s, t, and u.

t = s;  t(1).f1(:)=0;
u = s;  u(2).f1(:)=0;

same = arrayfun(@(x,y,z) isequal(x.f1, y.f1, z.f1), s, t, u)

This code returns

same =
     0     0     1

More About

collapse all

Tall Array Support

This function supports tall arrays with the limitations:

  • The specified 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 set to true (default), 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