MATLAB^®

structfun - Apply function to each field of scalar structure

Syntax

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

Description

A = structfun(fun, S) applies the function specified by fun to each field of scalar structure S, and returns the results in array A. fun is a function handle to a function that takes one input argument and returns a scalar value. Return value A is a column vector that has one element for each field in input structure S. The Nth element of A is the result of applying fun to the Nth field of S, and the order of the fields is the same as that returned by a call to fieldnames. (A is returned as one or more scalar structures when the UniformOutput option is set to false. See the table below.))

fun must return values of the same class each time it is called. If fun is a handle to an overloaded function, then structfun follows MATLAB dispatching rules in calling the function.

[A, B, ...] = structfun(fun, S) returns arrays A, B, ..., each array 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 can return output arguments having different classes, but the class of each output must be the same each time fun is called.

[A, ...] = structfun(fun, S, 'param1', value1, ...) enables you to specify optional parameter name/parameter value pairs. Parameters are

Parameter	Value
`'UniformOutput'`	Logical value indicating whether or not the outputs of `fun` can be returned without encapsulation in a structure. The default value is `true`. If equal to logical 1 (`true`), `fun` must return scalar values that can be concatenated into an array. The outputs can be any of the following types: numeric, logical, char, struct, or cell. If equal to logical 0 (`false`), `structfun` returns a scalar structure or multiple scalar structures having fields that are the same as the fields of the input structure `S`. The values in the output structure fields are the results of calling `fun` on the corresponding values in the input structure `B`. In this case, the outputs can be of any data type.
`'ErrorHandler'`	Function handle specifying the function MATLAB is to call if the call to `fun` fails. MATLAB calls the error handling function 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 field names) 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`. For 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.

Parameter

Value

'UniformOutput'

Logical value indicating whether or not the outputs of fun can be returned without encapsulation in a structure. The default value is true.

If equal to logical 1 (true), fun must return scalar values that can be concatenated into an array. The outputs can be any of the following types: numeric, logical, char, struct, or cell.

If equal to logical 0 (false), structfun returns a scalar structure or multiple scalar structures having fields that are the same as the fields of the input structure S. The values in the output structure fields are the results of calling fun on the corresponding values in the input structure B. In this case, the outputs can be of any data type.

'ErrorHandler'

Function handle specifying the function MATLAB is to call if the call to fun fails. MATLAB calls the error handling function 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 field names) 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.
For 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.

Examples

To create shortened weekday names from the full names, for example: Create a structure with strings in several fields:

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

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

structfun - Apply function to each field of scalar structure

Syntax

Description

Examples

See Also