HOWTO · MATLAB
How to Return Multiple Values From a MATLAB Function
Learn to define MATLAB functions with multiple outputs, select the results a caller needs, and group related values in a structure or cell array.
On this page
A MATLAB function can return several separate outputs from one call. The function declares output variables in its signature, assigns each variable in its body, and the caller receives values in that same order. When the values form one logical record, return a structure or cell array instead; that is a single output containing several fields or elements.
How MATLAB Functions Return Multiple Outputs
Square brackets in a function definition list separate outputs, in order. For example, [sumValue, diffValue] declares two outputs. They are not packed into a special “multiple return” object: each output is an ordinary value assigned to the corresponding caller variable. A function must assign an output before it returns if a caller requests that output.
This distinction matters when choosing a calling pattern. A caller can request the first output alone or request several outputs. It cannot skip a position by leaving a blank; use ~ for a position whose value is not needed. Structures and cell arrays follow a different pattern: the function returns one structure or one cell array, and the caller selects its fields or elements afterward.
Define and Call a Function With Multiple Outputs
The function signature names each output, and the body assigns each one. In MATLAB, a named function can use the form function [sumValue, diffValue, productValue] = calculate(a, b). This self-contained Octave example uses an anonymous function handle with deal to make the three-output call runnable in one script while retaining the original calculation.
Run this example:
calculate = @(a, b) deal(a + b, a - b, a * b);
[sumValue, diffValue, productValue] = calculate(5, 3);
printf("sum = %d\ndifference = %d\nproduct = %d\n", sumValue, diffValue, productValue);
sum = 8
difference = 2
product = 15
The function handle returns the sum, difference, and product in order. The caller binds them to sumValue, diffValue, and productValue in that same order. For a standalone MATLAB function, save a named function in a file whose name matches the function name; the syntax shown above declares its three output variables explicitly.
Capture Only the Outputs You Need
If a function returns [first, second, third], a call that assigns two variables receives the first two outputs and leaves the third unrequested. To retain the third value while ignoring the second, use [first, ~, third] = functionName(inputs). The tilde is a placeholder for an output position; it does not change what the function computes.
Choose the requested number and positions to match the task. If you need only one result and it is the first output, assign one variable. If you need a later output, include placeholders for earlier positions. Check the declaration when a value appears in the wrong variable: MATLAB associates outputs by position, not by the caller’s variable names.
Group Related Results in a Structure or Cell Array
Return a structure when results have meaningful names or represent one record. For example, a function can assign result.total = a + b and result.count = 2, then declare just function result = summarize(a, b). The caller receives one value and reads summary.total or summary.count. Named fields make the meaning visible at the point of use and allow related fields to be added without expanding a multi-output call signature.
A cell array is also one output, useful when grouped items may have different types or are naturally accessed by position. A function can build items = {a + b, a - b, "computed"} and return items; the caller accesses an element’s contents with curly braces, such as result{1}. Since positions have no descriptive names, document their meaning or prefer a structure when readers need to identify each item without remembering an index.
Neither a structure nor a cell array creates multiple function outputs by itself. The function signature still has one output variable in these examples; the returned value happens to contain multiple pieces of data.
Choose the Right Output Pattern
Use separate outputs when each result has a distinct, predictable role and callers commonly need different subsets, such as a value and its status. Their order is part of the function’s interface, so keep it stable and document it. Use a structure when the values belong together as a named record, especially when descriptive field names make calls easier to understand. Use a cell array when a positional collection is useful and its members may differ in type.
Choose based on how callers will use the data, not an assumed speed advantage. If output count or meaning varies by mode, consider a consistently shaped structure rather than making callers infer what each position means.
Common Mistakes and Troubleshooting
- A requested output is unassigned: assign every output that callers may request along each path through the function.
- Values appear in the wrong variables: compare the order in the function’s output list with the caller’s assignment list; names do not establish a mapping.
- A call asks for too many outputs: make the number of requested outputs consistent with the function definition, or update the definition and its callers together.
- A result is treated as a separate output when it is grouped: a function returning
resulthas one output. Useresult.fieldfor a structure orresult{index}for a cell array. - An unneeded middle output is required to reach a later one: put
~in that position, keeping the later output at its declared position.
When debugging, inspect the function signature, assignments to its outputs, and the caller’s left-hand side together. This usually reveals whether the issue is a missing assignment, a count mismatch, or an ordering assumption.