cellfun — Apply a function to each cell element in MATLAB and RunMat.
cellfun maps a function over one or more cell arrays, using each cell's contents as callback arguments. 'UniformOutput' controls array-versus-cell result collection, and 'ErrorHandler' hooks follow MATLAB semantics.
Syntax
Y = cellfun(func, C)
Y = cellfun(func, C1, C2, ...)
Y = cellfun(func, C..., "UniformOutput", tf)
Y = cellfun(func, C..., "ErrorHandler", errfunc)
Y = cellfun(func, C..., "UniformOutput", tf, "ErrorHandler", errfunc)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
func | Any | Yes | — | Function handle or builtin/function name. |
C | Any | Yes | — | Input cell array. |
C | Any | Variadic | — | One or more input cell arrays followed by optional extra callback args. |
C | Any | Variadic | — | Cell input arrays and optional callback args. |
UniformOutput | StringScalar | Yes | "UniformOutput" | Name-value key for uniform output mode. |
tf | Any | Yes | true | Logical scalar, or legacy double scalar 0 or 1, selecting uniform output. |
ErrorHandler | StringScalar | Yes | "ErrorHandler" | Name-value key for callback error handler. |
errfunc | Any | Yes | — | Error handler function handle or name. |
Returns
| Name | Type | Description |
|---|---|---|
Y | Any | Mapped callback outputs. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:cellfun:InvalidInput | Input callback/cell-array arguments or name-value forms are invalid. | cellfun: invalid input arguments |
RunMat:cellfun:UniformOutput | UniformOutput mode requirements are violated. | cellfun: uniform output contract violated |
RunMat:cellfun:FunctionError | Callback-related function execution semantics fail. | cellfun: callback execution error |
RunMat:UndefinedFunction | External callable resolution fails at runtime boundary. | cellfun: undefined external function |
| — | Internal allocation or struct materialization fails. | cellfun: internal error |
How cellfun works
- All cell array inputs must share the same size. Extra arguments that are not cell arrays are treated as constants and forwarded to every invocation.
- The callback may be supplied as a function handle (
@sin), an anonymous function, or one of MATLAB's short string identifiers (for example'isempty'or'isclass'). - With
'UniformOutput', true(default) the callback must return scalars (numeric, logical, or complex). The results are packed into an array that mirrors the cell array shape. Mixed real/complex outputs automatically promote to complex. - Uniform typed-integer scalar results preserve the exact class and native storage for all eight integer classes; mixed integer classes and integer/double mixtures are rejected.
UniformOutputaccepts logical scalars or legacy double scalars exactly equal to 0 or 1. Typed-integer, single-precision, text, and other numeric control values are rejected.- With
'UniformOutput', falsethe callback may return arbitrary values; RunMat stores them in a new cell array that matches the input dimensions. 'ErrorHandler', handlerintercepts runtime errors. When the callback throws, RunMat callshandler(errStruct, cellValue1, cellValue2, ..., extraArg1, extraArg2, ...). The structure contains the fieldsidentifier,message,index(1-based linear index), andindices(1×N vector of subscripts). The handler's return value is inserted into the result.- The public multiple-callback-output form remains a general runtime gap; the current callback path requests one result per cell.
Does RunMat run cellfun on the GPU?
cellfun itself is host-controlled. RunMat gathers GPU-resident inputs before calling the callback. Uniform packed output is materialized on the host, while 'UniformOutput', false stores callback results in cells without gathering a returned GPU value.
Examples
Computing string lengths across a cell array
C = {'apple', 'banana', 'cherry'};
lengths = cellfun(@length, C)Expected output:
lengths =
5 6 6Mapping across two cell arrays in lockstep
A = {1, 2, 3};
B = {4, 5, 6};
totals = cellfun(@plus, A, B)Expected output:
totals =
5 7 9Keeping non-scalar outputs as cells
names = {'Ada', 'Linus', 'Katherine'};
upper = cellfun(@upper, names, 'UniformOutput', false)Expected output:
upper =
1×3 cell array
{'ADA'} {'LINUS'} {'KATHERINE'}Supplying additional arguments alongside each cell
C = {magic(3), eye(3)};
diag3 = cellfun('size', C, 2)Expected output:
diag3 =
3 3Handling callback failures with 'ErrorHandler'
C = {'42', 'NaN', '3.14'};
handler = @(err, value) NaN;
numbers = cellfun(@str2double, C, 'ErrorHandler', handler)Expected output:
numbers =
42 NaN 3.1400Using builtin short names instead of function handles
cells = {[], 1:5, zeros(0, 3)};
empty_flags = cellfun('isempty', cells)Expected output:
empty_flags =
1 0 1Returning rich metadata in the error handler
cells = {1, 'two', 3};
eh = @(err, value) sprintf('%s @ %d', err.identifier, err.index);
results = cellfun(@(x) x + 1, cells, 'UniformOutput', false, 'ErrorHandler', eh)Expected output:
results =
1×3 cell array
{[2]} {[117 120 112]} {[4]}Using cellfun with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how cellfun changes the result.
Run a small cellfun example, explain the result, then change one input and compare the output.
FAQ
Does cellfun modify the original cell array?⌄
No. The builtin reads the cell contents, calls the supplied function, and returns a new array. The original cell array is never mutated.
What happens when the callback returns mixed real and complex values?⌄
RunMat promotes the entire output to a complex array when 'UniformOutput', true. Real results are converted to complex numbers with zero imaginary parts to match MATLAB.
Can the callback return strings or structs?⌄
Yes, but you must specify 'UniformOutput', false. That tells RunMat to collect results into a cell array rather than forcing scalar concatenation.
Are GPU arrays supported?⌄
Inputs that live on the GPU are gathered before the callback executes. Uniform packed output is host-resident; with 'UniformOutput', false, a GPU value returned by the callback remains resident inside the result cell.
How are errors reported to 'ErrorHandler'?⌄
The handler receives a structure with identifier, message, index, and indices fields followed by the values that triggered the error. Returning a value from the handler lets execution continue; rethrowing propagates the failure just like MATLAB.
Do extra non-cell arguments need to be the same size as the cells?⌄
No. Extra arguments are treated as constants and forwarded unchanged for every element. Only the cell array inputs must agree on size.
Can cellfun be used with anonymous functions that capture variables?⌄
Absolutely. Captures are forwarded to the generated closure before the cell elements, so anonymous functions behave the same way they do in MATLAB.
What are the default output types for empty inputs?⌄
When the cell arrays are empty and 'UniformOutput', true, RunMat returns an empty double array (size matches the input). For 'UniformOutput', false, the result is an empty cell array.
Does cellfun support MATLAB's 'isclass' short name?⌄
Yes. RunMat maps 'isclass' to the class builtin internally so you can write cellfun('isclass', C, 'double') just like in MATLAB.
What does cellfun do in MATLAB?⌄
cellfun applies a function to each cell of a cell array and returns the collected results. For example, cellfun(@length, C) returns the length of each cell's contents.
How is cellfun different from arrayfun?⌄
cellfun operates on cell arrays, while arrayfun operates on numeric or logical arrays. Use cellfun when your data is stored in cells (e.g., variable-length strings), and arrayfun for uniform numeric data.
Can cellfun return non-uniform outputs?⌄
Yes. Set 'UniformOutput' to false to collect results into a cell array when the function returns different sizes or types across cells.
Which built-in function names can I pass as strings to cellfun?⌄
— MATLAB's classic shorthand strings are all supported: 'isempty', 'islogical', 'isreal', 'length', 'ndims', 'prodofsize', and 'size'. RunMat also maps 'isclass' to the class builtin so you can write cellfun('isclass', C, 'double') just like in MATLAB.
When should I use cellfun vs arrayfun vs a plain for loop?⌄
— Use cellfun for cell arrays (variable-size or heterogeneous contents), arrayfun for numeric/logical arrays where each element is a scalar input, and a plain for loop whenever the body is non-trivial or you need side effects. A loop is often clearer and not meaningfully slower than cellfun — especially with 'UniformOutput', false, where both do element-by-element packing.
Related Cells functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how cellfun is executed, line by line, in Rust.
- View the source for cellfun in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.