nargoutchk (MATLAB Functions)

Validate number of output arguments

Syntax

msgstring = nargoutchk(minargs, maxargs, numargs)
msgstring = nargoutchk(minargs, maxargs, numargs, 'string')
msgstruct = nargoutchk(minargs, maxargs, numargs, 'struct')

Description

Use nargoutchk inside an M-file function to check that the desired number of output arguments is specified in the call to that function.

msgstring = nargoutchk(minargs, maxargs, numargs) returns an error message string msgstring if the number of outputs specified in the call, numargs, is less than minargs or greater than maxargs. If numargs is between minargs and maxargs (inclusive), nargoutchk returns an empty matrix.

It is common to use the nargout function to determine the number of output arguments specified in the call.

msgstring = nargoutchk(minargs, maxargs, numargs, 'string') is essentially the same as the command shown above, as nargoutchk returns a string by default.

msgstruct = nargoutchk(minargs, maxargs, numargs, 'struct') returns an error message structure msgstruct instead of a string. The fields of the return structure contain the error message string and a message identifier. If numargs is between minargs and maxargs (inclusive), nargoutchk returns an empty structure.

When too few outputs are supplied, the message string and identifier are

       message: 'Not enough output arguments.'
    identifier: 'MATLAB:nargoutchk:notEnoughOutputs'

When too many outputs are supplied, the message string and identifier are

       message: 'Too many output arguments.'
    identifier: 'MATLAB:nargoutchk:tooManyOutputs'

Remarks

nargoutchk is often used together with the error function. The error function accepts either type of return value from nargoutchk: a message string or message structure. For example, this command provides the error function with a message string and identifier regarding which error was caught:

error(nargoutchk(2, 4, nargout, 'struct'))

If nargoutchk detects no error, it returns an empty string or structure. When nargoutchk is used with the error function, as shown here, this empty string or structure is passed as an input to error. When error receives an empty string or structure, it simply returns and no error is generated.

Examples

You can use nargoutchk to determine if an M-file has been called with the correct number of output arguments. This example uses nargout to return the number of output arguments specified when the function was called. The function is designed to be called with one, two, or three output arguments. If called with no arguments or more than three arguments, nargoutchk returns an error message:

function [s, varargout] = mysize(x)
msg = nargoutchk(1, 3, nargout);
if isempty(msg)
    nout = max(nargout, 1) - 1;
    s = size(x);
    for k = 1:nout, varargout(k) = {s(k)}; end
else
    disp(msg)
end

See Also

nargchk, nargout, nargin, varargout, varargin, error

nargin, nargout native2unicode