Learn more about MATLAB

Function Arguments

On this page…
Overview Input Arguments Output Arguments Passing Arguments in Structures or Cell Arrays Passing Optional Arguments

Overview

When calling a function, the caller provides the function with any data it needs by passing the data in an argument list. Data that needs to be returned to the caller is passed back in a list of return values.

Semantically speaking, the MATLAB software always passes argument data by value. (Internally, MATLAB optimizes away any unnecessary copy operations.) If you pass data to a function that then modifies this data, you will need to update your own copy of the data. You can do this by having the function return the updated value as an output argument.

Back to Top

Input Arguments

The MATLAB software accepts input arguments in either of two different formats. See Command vs. Function Syntax for information on how to use these formats.

Passing String Arguments

When using the function syntax to pass a string literal to a function, you must enclose the string in single quotation marks, ('string'). For example, to create a new directory called myapptests, use

mkdir('myapptests')

However, if you are passing a variable to which a string has been assigned, use the variable name alone, without quotation marks. This example passes the variable dirname:

dirname = 'myapptests';
mkdir(dirname)

Passing Filename Arguments

You can specify a filename argument using the MATLAB command or function syntax. For example, either of the following are acceptable. (The .mat file extension is optional for save and load):

load mydata.mat           % Command syntax
load('mydata.mat')        % Function syntax

If you assign the output to a variable, you must use the function syntax:

savedData = load('mydata.mat')

Specify ASCII files as shown here. In this case, the file extension is required:

load mydata.dat -ascii            % Command syntax
load('mydata.dat','-ascii')       % Function syntax

Determining Filenames at Run-Time.   There are several ways that your function code can work on specific files without your having to hardcode their filenames into the program. You can

• Pass the filename as an argument:

  function myfun(datafile)
  

• Prompt for the filename using the input function:

  filename = input('Enter name of file:  ', 's');
  

• Browse for the file using the uigetfile function:

  [filename, pathname] = uigetfile('*.mat', 'Select MAT-file');

Passing Function Handle Arguments

The MATLAB function handle has several uses, the most common being a means of immediate access to the function it represents. You can pass function handles in argument lists to other functions, enabling the receiving function to make calls by means of the handle.

To pass a function handle, include its variable name in the argument list of the call:

fhandle = @humps;
x = fminbnd(fhandle, 0.3, 1);

The receiving function invokes the function being passed using the usual MATLAB calling syntax:

function [xf, fval, exitflag, output] = ...
         fminbnd(fhandle, ax, bx, options, varargin)
            .
            .
            .
113  fx = fhandle(x, varargin{:});

Back to Top

Output Arguments

To receive data output from a function, you must use the function calling syntax. This is not supported when you use command calling syntax

Assigning Output Arguments

Use the syntax shown here to store any values that are returned by the function you are calling. To store one output, put the variable that is to hold that output to the left of the equal sign:

vout = myfun(vin1, vin2, ...);

To store more than one output, list the output variables inside square brackets and separate them with commas or spaces:

[vout1 vout2 ...] = myfun(vin1, vin2, ...);

The number of output variables in your function call statement does not have to match the number of return values declared in the function being called. For a function that declares N return values, you can specify anywhere from zero to N output variables in the call statement. Any return values that you do not have an output variable for are discarded.

Functions return output values in the order in which the corresponding output variables appear in the function definition line within the M-file. This function returns 100 first, then x * y, and lastly x.^2:

function [a b c] = myfun(x, y)
b = x * y;    a = 100;    c = x.^2;

If called with only one output variable in the call statement, the function returns only 100 and discards the values of b and c. If called with no outputs, the functions returns 100 in the MATLAB default variable ans.

Assigning Optional Return Values

The section Passing Variable Numbers of Arguments describes the method of returning optional outputs in a cell array called varargout. A function that uses varargout to return optional values has a function definition line that looks like one of the following:

function varargout = myfun(vin1, vin2, ...)
function [vout1 vout2 ... varargout] = myfun(vin1, vin2, ...)

The code within the function builds the varargout cell array. The content and order of elements in the cell array determines how MATLAB assigns optional return values to output variables in the function call.

In the case where varargout is the only variable shown to the left of the equal sign in the function definition line, MATLAB assigns varargout{1} to the first output variable, varargout{2} to the second, and so on. If there are other outputs declared in the function definition line, then MATLAB assigns those outputs to the leftmost output variables in the call statement, and then assigns outputs taken from the varargout array to the remaining output variables in the order just described.

This function builds the varargout array using descending rows of a 5-by-5 matrix. The function is capable of returning up to six outputs:

function varargout = byRow(a)
varargout{1} = '    With VARARGOUT constructed by row ...';
for k = 1:5
    row = 5 - (k-1);              % Reverse row order
    varargout{k+1} = a(row,:);
end

Call the function, assigning outputs to four variables. MATLAB returns varargout{1:4}, with rows of the matrix in varargout{2:4} and in the order in which they were stored by the function:

[text r1 r2 r3] = byRow(magic(5))
text =
    With VARARGOUT constructed by row ...
r1 =
    11    18    25     2     9
r2 =
    10    12    19    21     3
r3 =
     4     6    13    20    22

A similar function builds the varargout array using diagonals of a 5-by-5 matrix:

function varargout = byDiag(a)
varargout{1} = '    With VARARGOUT constructed by diagonal ...';
for k = -4:4
    varargout{k + 6} = diag(a, k);
end

Call the function with five output variables. Again, MATLAB assigns elements of varargout according to the manner in which it was constructed within the function:

[text d1 d2 d3 d4] = byDiag(magic(5))
text =
    With VARARGOUT constructed by diagonal ...
d1 =
    11
d2 =
    10
    18
d3 =
     4
    12
    25
d4 =
    23
     6
    19
     2

Returning Modified Input Arguments

If you pass any input variables that the function can modify, you will need to include the same variables as output arguments so that the caller receives the updated value.

For example, if the function readText, shown below, reads one line of a file each time is it called, then it must keep track of the offset into the file. But when readText terminates, its copy of the offset variable is cleared from memory. To keep the offset value from being lost, readText must return this value to the caller:

function [text, offset] = readText(filestart, offset)

Back to Top

Passing Arguments in Structures or Cell Arrays

Instead of requiring an additional argument for every value you want to pass in a function call, you can package them in a MATLAB structure or cell array.

Passing Arguments in a Structure

Make each input you want to pass a separate field in the structure argument, using descriptive names for the fields. Structures allow you to change the number, contents, or order of the arguments without having to modify the function. They can also be useful when you have a number of functions that need similar information.

This example updates weather statistics from information in the following chart.

City	Temp.	Heat Index	Wind Speed	Wind Chill
Boston	43	32	8	37
Chicago	34	27	3	30
Lincoln	25	17	11	16
Denver	15	-5	9	0
Las Vegas	31	22	4	35
San Francisco	52	47	18	42

The information is stored in structure W. The structure has one field for each column of data:

W = struct('city', {'Bos','Chi','Lin','Dnv','Vgs','SFr'}, ...
           'temp', {43, 34, 25, 15, 31, 52}, ...
           'heatix', {32, 27, 17, -5, 22, 47}, ...
           'wspeed', {8, 3, 11, 9, 4, 18}, ...
           'wchill', {37, 30, 16, 0, 35, 42});

To update the data base, you can pass the entire structure, or just one field with its associated data. In the call shown here, W.wchill is a comma-separated list:

updateStats(W.wchill);

Passing Arguments in a Cell Array

You can also group arguments into cell arrays. The advantage over structures is that cell arrays are referenced by index, allowing you to loop through a cell array and access each argument passed in or out of the function. The disadvantage is that you do not have field names to describe each variable.

This example passes several attribute-value arguments to the plot function:

X = -pi:pi/10:pi;
Y = tan(sin(X)) - sin(tan(X));

C{1,1} = 'LineWidth';         C{2,1} = 2;
C{1,2} = 'MarkerEdgeColor';   C{2,2} = 'k';
C{1,3} = 'MarkerFaceColor';   C{2,3} = 'g';

plot(X, Y, '--rs', C{:})

Back to Top

Passing Optional Arguments

When calling a function, there are often some arguments that you must always specify, and others that are optional. For example, the sort function accepts one to three inputs and returns zero to two outputs:

Create a 7-by-7 numeric matrix, A, and sort it along the first dimension in ascending order:

A = magic(7);
sort(A, 1, 'ascend');

The first input in this call is the matrix to be sorted and is always required. The second and third inputs (dimension and mode, respectively) are optional. If you do not specify a value for either of the optional inputs, MATLAB uses its default value instead. For sort, the default second and third inputs select an ascending sort along the first dimension. If that is the type of sort you intend to do, then you can replace the second command above with the following:

sort(A);

In the same manner, some output arguments may be optional as well. In this case, the values for any outputs not specified in the call are simply not returned. The first command shown below returns the sorted matrix in B and the indices used to sort the matrix in ind. The second command returns only the sorted matrix. And the third command returns no values, displaying output to the terminal screen instead:

[B, ind] = sort(A);        % Return sorted matrix and indices.
B = sort(A);               % Return sorted matrix.
sort(A);                   % Display output.

You can also ignore outputs when calling a function or ignore certain inputs when writing a function. The command below requests only the matrix of indices (variable ind) from the sort function. The tilde (~) operator tells MATLAB that the output that holds this position in the argument list is not needed by the caller:

[~, ind] = sort(A)

Passing Variable Numbers of Arguments

The varargin and varargout functions let you pass any number of inputs or return any number of outputs to a function. This section describes how to use these functions and also covers

• Unpacking varargin Contents

• Packing varargout Contents

• Using varargin and varargout in Argument Lists

MATLAB packs all specified input arguments into a cell array, a special kind of MATLAB array in which the array elements are cells. Each cell can hold any size or kind of data — one might hold a vector of numeric data, another in the same array might hold an array of string data, and so on. For output arguments, your function code must pack them into the varargout cell array so that MATLAB can return the arguments to the caller.

Here is an example function that accepts any number of two-element vectors and draws a line to connect them:

function testvar(varargin)
for k = 1:length(varargin)
   x(k) = varargin{k}(1);           % Cell array indexing
   y(k) = varargin{k}(2);
end
xmin = min(0,min(x));
ymin = min(0,min(y));
axis([xmin fix(max(x))+3 ymin fix(max(y))+3])
plot(x,y)

Coded this way, the testvar function works with various input lists; for example,

testvar([2 3],[1 5],[4 8],[6 5],[4 2],[2 3])
testvar([-1 0],[3 -5],[4 2],[1 1])

Unpacking varargin Contents.   Because varargin contains all the input arguments in a cell array, it is necessary to use cell array indexing to extract the data. For example,

y(n) = varargin{n}(2);

Cell array indexing has two subscript components:

• The indices within curly braces {} specify which cell to get the contents of.

• The indices within parentheses () specify a particular element of that cell.

In the preceding code, the indexing expression {i} accesses the nth cell of varargin. The expression (2) represents the second element of the cell contents.

Packing varargout Contents.   When allowing a variable number of output arguments, you must pack all of the output into the varargout cell array. Use nargout to determine how many output arguments the function is called with. For example, this code accepts a two-column input array, where the first column represents a set of x coordinates and the second represents y coordinates. It breaks the array into separate [xi yi] vectors that you can pass into the testvar function shown at the beginning of the section on Passing Variable Numbers of Arguments:

function [varargout] = testvar2(arrayin)
for k = 1:nargout
   varargout{k} = arrayin(k,:);   % Cell array assignment
end

The assignment statement inside the for loop uses cell array assignment syntax. The left side of the statement, the cell array, is indexed using curly braces to indicate that the data goes inside a cell. For complete information on cell array assignment, see the documentation on Cell Arrays.

To call testvar2, type

a = [1 2; 3 4; 5 6; 7 8; 9 0];

[p1, p2, p3, p4, p5] = testvar2(a)
p1 =
     1     2
p2 =
     3     4
p3 =
     5     6
p4 =
     7     8
p5 =
     9     0

Using varargin and varargout in Argument Lists.   varargin or varargout must appear last in the argument list, following any required input or output variables. That is, the function call must specify the required arguments first. For example, these function declaration lines show the correct placement of varargin and varargout:

function [out1,out2] = example1(a,b,varargin)
function [i,j,varargout] = example2(x1,y1,x2,y2,flag)

Checking the Number of Input Arguments

The nargin and nargout functions enable you to determine how many input and output arguments a function is called with. You can then use conditional statements to perform different tasks depending on the number of arguments. For example,

function c = testarg1(a, b)
if (nargin == 1)
    c = a .^ 2;
elseif (nargin == 2)
    c = a + b;
end

Given a single input argument, this function squares the input value. Given two inputs, it adds them together.

Here is a more advanced example that finds the first token in a character string. A token is a set of characters delimited by white space or some other character. Given one input, the function assumes a default delimiter of white space; given two, it lets you specify another delimiter if desired. It also allows for two possible output argument lists:

function [token, remainder] = strtok(string, delimiters)
% Function requires at least one input argument
if nargin < 1
   error('Not enough input arguments.');
end
token = []; remainder = [];
len = length(string);
if len == 0
   return
end

% If one input, use white space delimiter
if (nargin == 1)
   delimiters = [9:13 32]; % White space characters
end
i = 1;

% Determine where nondelimiter characters begin
while (any(string(i) == delimiters))
   i = i + 1;
   if (i > len), return, end
end

% Find where token ends
start = i;
while (~any(string(i) == delimiters))
   i = i + 1;
   if (i > len), break, end
end
finish = i - 1;
token = string(start:finish);

% For two output arguments, count characters after
% first delimiter (remainder)
if (nargout == 2)
   remainder = string(finish+1:end);
end

The strtok function is a MATLAB M-file in the strfun directory.

Note   The order in which output arguments appear in the function declaration line is important. The argument that the function returns in most cases appears first in the list. Additional, optional arguments are appended to the list.

Passing Optional Arguments to Nested Functions

You can use optional input and output arguments with nested functions, but you should be aware of how MATLAB interprets varargin, varargout, nargin, and nargout under those circumstances.

varargin and varargout are variables and, as such, they follow exactly the same scoping rules as any other MATLAB variable. Because nested functions share the workspaces of all outer functions, varargin and varargout used in a nested function can refer to optional arguments passed to or from the nested function, or passed to or from one of its outer functions.

nargin and nargout, on the other hand, are functions and when called within a nested function, always return the number of arguments passed to or from the nested function itself.

Using varargin and varargout.   varargin or varargout used in a nested function can refer to optional arguments passed to or from that function, or to optional arguments passed to or from an outer function.

• If a nested function includes varargin or varargout in its function declaration line, then the use of varargin or varargout within that function returns optional arguments passed to or from that function.

• If varargin or varargout are not in the nested function declaration but are in the declaration of an outer function, then the use of varargin or varargout within the nested function returns optional arguments passed to the outer function.

In the example below, function C is nested within function B, and function B is nested within function A. The term varargin{1} in function B refers to the second input passed to the primary function A, while varargin{1} in function C refers to the first argument, z, passed from function B:

function x = A(y, varargin)   % Primary function A
B(nargin, y * rand(4))

   function B(argsIn, z)      % Nested function B
   if argsIn >= 2
      C(z, varargin{1}, 4.512, 1.729)
   end

      function C(varargin)    % Nested function C
      if nargin >= 2
         x = varargin{1}
      end
      end   % End nested function C
   end   % End nested function B
end   % End primary function A

Using nargin and nargout.   When nargin or nargout appears in a nested function, it refers to the number of inputs or outputs passed to that particular function, regardless of whether or not it is nested.

In the example shown above, nargin in function A is the number of inputs passed to A, and nargin in function C is the number of inputs passed to C. If a nested function needs the value of nargin or nargout from an outer function, you can pass this value in as a separate argument, as done in function B.

Example of Passing Optional Arguments to Nested Functions.   This example references the primary function's varargin cell array from each of two nested functions. (Because the workspace of an outer function is shared with all functions nested within it, there is no need to pass varargin to the nested functions.)

Both nested functions make use of the nargin value that applies to the primary function. Calling nargin from the nested function would return the number of inputs passed to that nested function, and not those that had been passed to the primary. For this reason, the primary function must pass its nargin value to the nested functions.

function meters = convert2meters(miles, varargin)
% Converts MILES (plus optional FEET and INCHES input)
% values to METERS.

if nargin < 1 || nargin > 3
   error('1 to 3 input arguments are required');
end

   function feet = convert2Feet(argsIn)
   % Nested function that converts miles to feet and adds in 
   % optional FEET argument.
   
   feet = miles .* 5280;
   
   if argsIn >= 2
      feet = feet + varargin{1};
   end
   end  % End nested function convert2Feet

   function inches = convert2Inches(argsIn)
   % Nested function that converts feet to inches and adds in 
   % optional INCHES argument.
   
   inches = feet .* 12;
   
   if argsIn == 3
      inches = inches + varargin{2};
   end
   end  % End nested function convert2Inches

feet = convert2Feet(nargin);
inches = convert2Inches(nargin);

meters = inches .* 2.54 ./ 100;
end  % End primary function convert2meters

convert2meters(5)
ans =
  8.0467e+003

convert2meters(5, 2000, 4.7)
ans =
  8.6564e+003

Ignoring Selected Outputs or Input Arguments

Using the tilde (~) operator, you can change the declaration of a function so that it ignores any one or more entries in the input argument list, or you can change the function calling code so that one or more selected values returned by the function are ignored. This can help you to keep your workspace clear of variables you have no use for, and also help you conserve memory.

You can ignore unneeded outputs when calling a function:

[vOut1, ~, ~, vOut4] = myTestFun;

You can ignore arguments in an input argument list when defining certain functions:

function myTestFun(argIn1, ~, argIn3);

Note   Each tilde operator in an input or output argument list must be separated from other arguments by a comma.

Ignoring Selected Outputs on a Function Call.   When you replace an output argument with the tilde operator, MATLAB does not return the value that corresponds to that place in the argument list.

The task performed by the following example is to see if the current working directory contains any M-files. The dos function returns up to two outputs: the completion status (where 0 equals success), and the results of the operation. In this example, you only need the status output. Returning the second output adds an unused variable m_files to the workspace, and wastes nearly 50KB of memory:

clear
[status, m_files] = dos('dir *.m');
whos
  Name         Size               Bytes  Class     Attributes

  m_files      1x24646            49292  char
  status       1x1                    8  double

Replacing the unused variable with the tilde operator resolves these problems:

clear
[status, ~] = dos('dir *.m');

status
status =
     0         % Zero status means success: M-files found

whos
  Name        Size            Bytes  Class     Attributes

  status      1x1                 8  double

The next example displays the names of all files in the current directory that have an xls extension. In the first call to fileparts, only the file extension is needed. In the second call, only the file name is desired, All other outputs are ~, and are thus ignored:

s = dir;    len = length(s);
for k=1:len
    [~, ~, fileExt] = fileparts(s(k).name);
    if strcmp(fileExt,'.xls')
        [~, xlsFile] = fileparts(s(k).name)
    end
end

xlsFile =
    my_accounts
xlsFile =
    team_schedule
xlsFile =
    project_goals

Ignoring Inputs in a Function Definition.   Callback functions and methods that implement a subclass are two examples of how you might find the tilde operator useful when fewer than the full number of inputs are required. When writing a callback function, you might have arguments required by the callback template that your own callback code has no use for. Just the same, you need to include these inputs in the argument list for your callback definition. Otherwise, MATLAB might not be able to execute the callback.

The following example callback uses only the first of the three inputs defined in the template. Invoking the callback as it is shown here puts two unused inputs into the function workspace:

function plot_popup_CreateFcn(hObject, eventdata, handles)
if ispc && isequal( ...
        get(hObject, 'BackgroundColor'), ...
        get(0,'defaultUicontrolBackground'))
set(hObject,'BackgroundColor','white');
end

Rewrite the top line of the callback function so that it replaces the two unused inputs with tilde. MATLAB now ignores any inputs passed in the call. This results in less clutter in the function workspace:

function plot_popup_CreateFcn(hObject, ~, ~)
if ispc && isequal( ...
        get(hObject, 'BackgroundColor'), ...
        get(0,'defaultUicontrolBackground'))
set(hObject,'BackgroundColor','white');
end

When writing the original callback in the MATLAB Editor, the M-Lint utility highlights the second and third input arguments. If you hover your mouse pointer over one of these arguments, M-Lint displays the following warning:

Click the button for each of the highlighted arguments, and MATLAB replaces each with the tilde operator:

Another use for tilde as an input argument is in the use of classes that are derived from a superclass. In many cases, inputs required by the superclass might not be needed when invoked on a method of a particular subclass. When writing the subclass method, replace inputs that are unused with tilde. By doing this, you conserve memory by not allowing unnecessary input values to be passed into the subclass method. You also reduce the number of variables in the workspace of your subclass methods.

Back to Top

Calling Functions

Validating Inputs with inputParser

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS