structfun

Apply function to each field of scalar structure

Syntax

[A1,...,An] = structfun(func,S)
[A1,...,An] = structfun(func,S,Name,Value)

Description

[A1,...,An] = structfun(func,S) applies the function specified by function handle func to each field of scalar structure S. Output arrays A1,...,An, where n is the number of outputs from function func, contain the outputs from the function calls.

[A1,...,An] = structfun(func,S,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 a single input argument and returns n 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.

S

Scalar structure.

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 structfun function combines the outputs in arrays A1,...,An, where n is the number of function outputs. Each output array is of the same type as the individual function outputs.

false (0)

Requests that the structfun function combine the outputs into scalar structures A1,...,An, with the same fields as input structure S. 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,...,An

Arrays that collect the n outputs from function func.

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 input. The class of the corresponding output array is the same as the class of the individual outputs from function func.

  • Each array A is a column vector whose length equals the number of fields in S. The structfun function applies function func to the fields of S in the same order as that returned by the fieldnames function.

If UniformOutput is false, each array A is a scalar structure with the same fields as input S.

Examples

Create a scalar structure, and count the number of characters in each field.

s.f1 = 'Sunday';
s.f2 = 'Monday';
s.f3 = 'Tuesday'; 
s.f4 = 'Wednesday';
s.f5 = 'Thursday';
s.f6 = 'Friday';
s.f7 = 'Saturday';

lengths = structfun(@numel, s)

Shorten the text in each field of s, created in the previous example. Because the output is nonscalar, set UniformOutput to false.

shortNames = structfun(@(x) ( x(1:3) ), s, 'UniformOutput', false)

The syntax @(x) creates an anonymous function.

Define and call a custom error handling function.

function result = errorfun(errorinfo, field)
   warning(errorinfo.identifier, errorinfo.message);
   result = NaN;
end

mystruct.f1 = 'text';
myresult = structfun(@(x) x^2, mystruct, 'ErrorHandler', @errorfun)

Related Examples

See Also

| | | |

Introduced before R2006a

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support