Tutorial

How to Validate the Number of Output Arguments Passed to a Function in MATLAB

Use the functions nargout or nargoutchk to validate the number of output arguments passed to a function.

Description

MATLAB validates automatically the number of outputs requested to a function, according to the definition and the body of the function. For example, the function computestats1 only accepts three inputs and up to two outputs.

function [minVal,maxVal] = computestats1(a,b,c)
sample = [a, b, c];
minVal = min(sample);
maxVal = max(sample);
end
% Call 'computestats1', requesting two outputs
[minVal1,maxVal1] = computestats1(1,2,3);
% Call 'computestats1', requesting three outputs
[minVal2,maxVal2,other2] = computestats1(1,2,3);

However, if a function supports a variable number of output arguments, the automatic validation is not possible. In this case, you should use the functions nargout or nargoutchk to validate the number of outputs requested to the function.

nargout

The statement nargout returns the number of output arguments passed to the currently executing function. It is used below to validate that only one or three outputs are requested to samplefunc in each call.

Learn here how to use logical operators in MATLAB.
function varargout = samplefunc()
if((nargout ~= 1) && (nargout ~= 3))    
    error('IPL:samplefunc:WrongNumberOfOutputs', 'This function only supports one or three outputs.');
end
for i = 1:nargout
    varargout{i} = i;
end
end
% Call 'samplefunc', requesting one output
a = samplefunc();
% Call 'samplefunc', requesting two outputs
[b,c] = samplefunc();

nargoutchk

The statement nargoutchk(minargs,maxargs) throws an error if the number of output arguments passed to the currently executing function is not in the range \([minargs,maxargs]\). It is used below to validate that only one, two or three outputs are requested to computestats2 in each call.

Specify Inf as maxargs to accept an unlimited number of inputs.
function varargout = computestats2(a,b,c)
nargoutchk(1,3);
sample = [a, b, c];
handles = {@min, @max, @mean};
for i = 1:nargout
    varargout{i} = handles{i}(sample);
end
end
% Call 'computestats2', requesting three outputs
[minVal3,maxVal3,meanVal3] = computestats2(1,2,3);
% Call 'computestats2', requesting zero outputs
computestats2(1,2,3);
% Call 'computestats2', requesting four outputs
[minVal4,maxVal4,meanVal4,other4] = computestats2(1,2,3);

Tip

The functions that allow a variable number of inputs and outputs should be documented in detail, because the set of supported inputs and outputs is not stated explicitly in the function declaration statement.

In most cases, the user just sees an input argument called “varargin” or an output argument called “varargout”. If the user does not know the meaning of these variables, the situation is even worse.

Learn here how to add help documentation to a function in MATLAB.

Further reading

I recommend the following books to learn more on functions in MATLAB.

  1. MATLAB: A Practical Introduction to Programming and Problem Solving (4th Edition)

    This book was the winner of a Textbook Excellence Award. The sixth chapter covers user-defined functions, scope of variables, debugging, and other aspects related to the development of MATLAB programs.

  2. MATLAB for Engineers (5th Edition)

    This excellent book is especially oriented to engineers and scientists who want to learn MATLAB programming. Chapter 6 explains how to create functions, including anonymous functions, local functions, and nested functions.

I also recommend the following pages in the MATLAB help documentation, and the other tutorials in this series.

doc nargout;
doc nargoutchk;

Exercise

Define a function called “dosomething” and ensure that it only accepts one, two or four output arguments. The function does not have inputs.

Source code

I hope you have learned how to validate the number of output arguments passed to a function in MATLAB. The source code developed in this tutorial is available at this page.

Share

Your friends may need this knowledge to complete a task. Share this tutorial.