arrayfun – Apply function to each element of array

Syntax

1
2
3
4

A = arrayfun(fun, S)
A = arrayfun(fun, S, T, ...)
[A, B, ...] = arrayfun(fun, S, ...)
[A, ...] = arrayfun(fun, S, ..., 'param1', value1, ...)

Description

A = arrayfun(fun, S) applies the function specified by fun to each element of array S, and returns the results in array A. The value A returned by arrayfun is the same size as S, and the (I,J,…)th element of A is equal to fun(S(I,J,…)). The first input argument 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 is bound to more than one built-in or M-file (that is, if it represents a set of overloaded functions), then the class of the values that arrayfun actually provides as input arguments to fun determines which functions are executed.

The order in which arrayfun computes elements of A is not specified and should not be relied upon.

A = arrayfun(fun, S, T, …) evaluates fun using elements of the arrays S, T, … as input arguments. The (I,J,…)th element of A is equal to fun(S(I,J,…), T(I,J,…), …). All input arguments must be of the same size.

[A, B, ...] = arrayfun(fun, S, …) evaluates fun, which is a function handle to a function that returns multiple outputs, and 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 can return output arguments having different classes, but the class of each output must be the same each time fun is called.

[A, ...] = arrayfun(fun, S, …, ‘param1′, value1, …) enables you to specify optional parameter name and value pairs. Parameters recognized by arrayfun are shown below. Enclose each parameter name with single quotes.

UniformOutput

A logical 1 (true) or 0 (false), indicating whether or not the outputs 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. These values can also be a cell array. If false, arrayfun returns a cell array (or multiple cell arrays), where the (I,J,…)th cell contains the value fun(S(I,J,…), …).

ErrorHandler

A function handle, specifying the function that arrayfun is to call if the call to fun fails. If an error handler is not specified, arrayfun rethrows the error from the call to fun.

Remarks

The MATLAB software provides two functions that are similar to arrayfun; these are structfun and cellfun. With structfun, you can apply a given function to all fields of one or more structures. With cellfun, you apply the function to all cells of one or more cell arrays.

Examples

Example 1 — Operating on a Single Input.

Create a 1-by-15 structure array with fields f1 and f2, each field containing an array of a different size. Make each f1 field be unequal to the f2 field at that same array index:

1
2
3
4

for k=1:15
   s(k).f1 = rand(k+3,k+7) * 10;
   s(k).f2 = rand(k+3,k+7) * 10;
end

Set three f1 fields to be equal to the f2 field at that array index:

1
2
3

s(3).f2 = s(3).f1;
s(9).f2 = s(9).f1;
s(12).f2 = s(12).f1;

Use arrayfun to compare the fields at each array index. This compares the array of s(1).f1 with that of s(1).f2, the array of s(2).f1 with that of s(2).f2, and so on through the entire structure array.

The first argument in the call to arrayfun is an anonymous function. Anonymous functions return a function handle, which is the required first input to arrayfun:

1
2
3

z = arrayfun(@(x)isequal(x.f1, x.f2), s)
z =
   0  0  1  0  0  0  0  0  1  0  0  1  0  0  0

Example 2 — Operating on Multiple Inputs.

This example performs the same array comparison as in the previous example, except that it compares the same field of more than one structure array rather than different fields of the same structure array. This shows how you can use more than one array input with arrayfun.

Make copies of array s, created in the last example, to arrays t and u.

1

t = s;   u = s;

Make one element of structure array t unequal to the same element of s. Do the same with structure array u:

1
2
3
4
5
6
7
8

t(4).f1(12)=0;
u(14).f1(6)=0;
 
Compare field f1 of the three arrays s, t, and u:
 
z = arrayfun(@(a,b,c)isequal(a.f1, b.f1, c.f1), s, t, u)
z =
   1  1  1  0  1  1  1  1  1  1  1  1  1  0  1

Example 3 — Generating Nonuniform Output.

Generate a 1-by-3 structure array s having random matrices in field f1:

1
2
3
4

rand('state', 0);
s(1).f1 = rand(7,4) * 10;
s(2).f1 = rand(3,7) * 10;
s(3).f1 = rand(5,5) * 10;

Find the maximum for each f1 vector. Because the output is nonscalar, specify the UniformOutput option as false:

1
2
3
4
5
6
7
8
9
10
11

sMax = arrayfun(@(x) max(x.f1), s, 'UniformOutput', false)
sMax = 
    [1x4 double]    [1x7 double]    [1x5 double]
 
sMax{:}
ans =
  9.5013  9.2181  9.3547  8.1317
ans =
  2.7219  9.3181  8.4622  6.7214  8.3812   8.318  7.0947
ans =
  6.8222  8.6001  8.9977  8.1797  8.385

Find the mean for each f1 vector:

1
2
3
4
5
6
7
8
9
10
11
12

sMean = arrayfun(@(x) mean(x.f1), s, ...
                'UniformOutput', false)
sMean = 
    [1x4 double]    [1x7 double]    [1x5 double]
 
sMean{:}
ans =
  6.2628  6.2171  5.4231  3.3144
ans =
  1.6209   7.079  5.7696  4.6665  5.1301  5.7136  4.8099
ans =
  3.8195  5.8816  6.9128  4.9022  5.9541

Example 4 — Assigning to More Than One Output Variable.

The next example uses the lu function on the same structure array, returning three outputs from arrayfun:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

[l u p] = arrayfun(@(x)lu(x.f1), s, 'UniformOutput', false)
l = 
    [7x4 double]    [3x3 double]    [5x5 double]
u = 
    [4x4 double]    [3x7 double]    [5x5 double]
p = 
    [7x7 double]    [3x3 double]    [5x5 double]
 
l{3}
ans =
       1          0         0         0         0
  0.44379         1         0         0         0
  0.79398   0.79936         1         0         0
  0.27799  0.066014  -0.77517         1         0
  0.28353   0.85338   0.29223   0.67036         1
 
u{3}
ans =
   6.8222    3.7837    8.9977    3.4197    3.0929
        0    6.9209    4.2232    1.3796    7.0124
        0         0   -4.0708  -0.40607   -2.3804
        0         0         0    6.8232    2.1729
        0         0         0         0  -0.35098
 
p{3}
ans =
     0     0     1     0     0
     0     0     0     1     0
     0     0     0     0     1
     1     0     0     0     0
     0     1     0     0     0

View matlabtutorials's Profile      Subscribe via RSS