Programming

Determining Which Function Is Called

When more than one function has the same name, which one does MATLAB call? This section explains the process that MATLAB uses to make this decision. It covers the following topics:

• Function Scope
• Precedence Order
• Multiple Implementation Types
• Querying Which Function MATLAB Will Call

Function Scope

Any functions you call must first be within the scope of (i.e., visible to) the calling function or your MATLAB session. MATLAB determines if a function is in scope by searching for the function's executable file according to a certain order (see Precedence Order).

One key part of this search order is the MATLAB path. The path is an ordered list of directories that MATLAB defines on startup. You can add or remove any directories you want from the path. MATLAB searches the path for the given function name, starting at the first directory in the path string and continuing until either the function file is found or the list of directories is exhausted. If no function of that name is found, then the function is considered to be out of scope and MATLAB issues an error.

Precedence Order

The function precedence order determines the precedence of one function over another based on the type of function and its location on the MATLAB path. MATLAB selects the correct function for a given context by applying the following function precedence rules in the order given here.

For items 3 through 7 in this list, the file MATLAB searches for can be any of five types: an M- or built-in (.bi) file, preparsed M-file (P-Code), compiled C or Fortran file (MEX-file), or Simulink^® model (MDL-file). See Multiple Implementation Types for more on this.

1. Variable

1. Before assuming that a name should match a function, MATLAB checks the current workspace to see if it matches a variable name. If MATLAB finds a match, it stops the search.

2. Subfunction

1. Subfunctions take precedence over all other M-file functions and overloaded methods that are on the path and have the same name. Even if the function is called with an argument of type matching that of an overloaded method, MATLAB uses the subfunction and ignores the overloaded method.

3. Private function

1. Private functions are called if there is no subfunction of the same name within the current scope. As with subfunctions, even if the function is called with an argument of type matching that of an overloaded method, MATLAB uses the private function and ignores the overloaded method.

4. Class constructor

1. Constructor functions (functions having names that are the same as the @ directory, for example @polynom/polynom.m) take precedence over other MATLAB functions. Therefore, if you create an M-file called polynom.m and put it on your path before the constructor @polynom/polynom.m version, MATLAB will always call the constructor version.

5. Overloaded method

1. MATLAB calls an overloaded method if it is not superseded by a subfunction or private function. Which overloaded method gets called depends on the classes of the objects passed in the argument list.

6. Function in the current directory

1. A function in the current working directory is selected before one elsewhere on the path.

7. Function elsewhere on the path

1. Finally, a function elsewhere on the path is selected. A function in a directory that is toward the beginning of the path string is given higher precedence.

Note    Because variables have the highest precedence, if you have created a variable of the same name as a function, MATLAB will not be able to run that function until you clear the variable from memory.

Multiple Implementation Types

There are five file precedence types. MATLAB uses file precedence to select between identically named functions in the same directory. The order of precedence for file types is

1. Built-in (.bi) file
2. MEX-files
3. MDL (Simulink® model) file
4. P-code file
5. M-file

For example, if MATLAB finds a P-code and an M-file version of a method in a class directory, then the P-code version is used. It is, therefore, important to regenerate the P-code version whenever you edit the M-file.

Querying Which Function MATLAB Will Call

You can determine which function MATLAB will call using the which command. For example,

• which pie3
  $matlabroot/toolbox/matlab/specgraph/pie3.m
  

However, if p is a portfolio object,

• which pie3(p)
  dir_on_your_path/@portfolio/pie3.m      % portfolio method
  

The which command determines which version of pie3 MATLAB will call if you passed a portfolio object as the input argument. To see a list of all versions of a particular function that are on your MATLAB path, use the -all option. See the which reference page for more information on this command.

MATLAB Calling Syntax

This section explains how to use the MATLAB command and function syntax:

• MATLAB Command Syntax
• MATLAB Function Syntax
• Passing Arguments with Command and Function Syntax

You can call function M-files from either the MATLAB command line or from within other M-files. Be sure to include all necessary arguments, enclosing input arguments in parentheses and output arguments in square brackets.

Note    Function names are sensitive to case. When you call a function, use the correct combination of upper and lowercase letters so that the name is an exact match. Otherwise, you risk calling a different function that does match but is elsewhere on the path.

You often have the choice of using one of two syntaxes for a function call. You can use either a command or a function type of syntax. This is referred to in MATLAB as command/function duality.

MATLAB Command Syntax

A function call made in command syntax consists of the function name followed by one or more arguments separated by spaces:

• functionname in1 in2 ... inN
  

While the command syntax is simpler to write, it has the restriction that you may not assign any return values the function might generate. Attempting to do so generates an error.

Two examples of command syntax are

• save mydata.mat x y z
  clear length width depth
  

In the command syntax, MATLAB treats all arguments as string literals.

MATLAB Function Syntax

Function calls written in the function syntax look essentially the same as those in many other programming languages. One difference is that, in MATLAB, functions can return more than one output value.

A function call with a single return value looks like this:

• out = functionname(in1, in2, ..., inN)
  

If the function returns more than one value, separate the output variables with commas or spaces, and enclose them all in square brackets ([]):

• [out1, out2, ..., outN] = functionname(in1, in2, ..., inN)
  

Here are two examples:

• copyfile(srcfile, '..\mytests', 'writable')
  [x1, x2, x3, x4] = deal(A{:})
  

In the function syntax, MATLAB passes arguments to the function by value. See the examples under Passing Arguments with Command and Function Syntax.

Passing Arguments with Command and Function Syntax

When you call a function using function syntax, MATLAB passes the values assigned to each variable in the argument list. For example, this expression passes the values assigned to A0, A1, and A2 to the polyeig function:

• e = polyeig(A0, A1, A2)
  

Function calls written in command syntax pass all arguments as string literals. This expression passes the strings 'mydata.mat', 'x', 'y', and 'z' to the save function:

• save mydata.mat x y z
  

The following examples show the difference between passing arguments in the two syntaxes.

Passing Arguments -- Example 1.   Calling disp with the function syntax, disp(A), passes the value of variable A to the disp function:

• A = pi;
  
  disp(A)                    % Function syntax
     3.1416
  

Calling it with the command syntax, disp A, passes the string 'A':

• A = pi;
  
  disp A                     % Command syntax
     A
  

Passing Arguments -- Example 2.   Passing two variables representing equal strings to the strcmp function using function and command syntaxes gives different results. The function syntax passes the values of the arguments. strcmp returns a 1, which means they are equal:

• str1 = 'one';       str2 = 'one';
  
  strcmp(str1, str2)                  % Function syntax
  ans =
     1        (equal)
  

The command syntax passes the names of the variables, 'str1' and 'str2', which are unequal:

• str1 = 'one';       str2 = 'one';
  
  strcmp str1 str2                    % Command syntax
  ans =
     0        (unequal)
  

Calling Functions

Passing Certain Argument Types

© 1994-2005 The MathWorks, Inc.