MATLAB - Function Precedence Order

MATLAB - Function and Variable Precedence

When you type a name like myFunction in MATLAB, how does it decide what to execute? It could be a variable, a built-in function, or a script you wrote. MATLAB follows a strict set of rules, known as the precedence order, to resolve this ambiguity. Understanding this order is crucial for avoiding unexpected behavior and writing robust code.

The Precedence Order

MATLAB searches for a name in the following order. The first match found is the one it uses.

1. Variable: MATLAB first checks if the name matches a variable in the current workspace. This is the highest precedence.
2. Imported Package Functions: Functions explicitly imported using import somePackage.myFunction;.
3. Nested Function: A function defined within the current function.
4. Local Function: A function defined in the same file as the calling script or function (a sub-function).
5. Private Function: A function located in a subfolder named private within the parent function’s folder.
6. Object Method: A method belonging to an object (myObject.myMethod). The method used depends on the class of the object.
7. Class Constructor: A constructor for a class, often found in a @ClassName folder or as a classdef file.
8. Loaded Simulink Model: A Simulink model that is currently loaded in memory.
9. Function on the MATLAB Path: Any .m file found in a folder on the MATLAB search path. This includes MATLAB’s built-in functions (like sum, plot) and functions from installed toolboxes.

Why This Matters: Common Pitfalls and Best Practices

Pitfall: Variable Shadowing

Because variables have the highest precedence, you can accidentally “shadow” or hide a function. This is a very common source of bugs.

%% Pitfall Example: Shadowing the 'sum' function

% Create a variable named 'sum'
sum = 10;

data = [1, 2, 3, 4, 5];

% This line will now cause an error!
try
    total = sum(data);
catch ME
    disp('Error caught!');
    disp(ME.message);
end

% MATLAB sees 'sum' and uses the variable (10), not the function.
% It tries to execute 10(data), which is invalid syntax.

% To fix this, clear the variable from the workspace
clear sum;

% Now it works as expected
total = sum(data);
disp(['The correct total is: ', num2str(total)]);

% Output:
% Error caught!
% Invalid use of operator.

Best Practices for Avoiding Name Conflicts

• Avoid Naming Variables After Functions: Never use common function names like sum, mean, plot, i, or j as variable names. i and j are built-in functions for complex numbers.
• Use the MATLAB Editor’s Linter: The MATLAB Editor automatically highlights shadowed functions and other potential issues with a wavy orange underline. Pay attention to these warnings.
• Check for Existence: Before naming a new function, use the exist or which command to see if the name is already in use. which plot will show you the path to the plot.m function.
• Leverage Local and Private Functions: For helper functions that are only used by one main script, define them as local functions in the same file or as private functions in a private subfolder. This limits their scope and prevents them from conflicting with other functions on the path.

Example: Local Function Precedence

A local function within a file will always be chosen over a function with the same name on the MATLAB path.

% mainScript.m
function mainScript()
    % This call will execute the local function defined below,
    % not any other 'calculate' function on the MATLAB path.
    result = calculate(5);
    fprintf('The result is: %d\n', result);
end

% Local function with higher precedence
function y = calculate(x)
    % This is our special, local version
    y = x * 100;
end

% -- To run this, save it as 'mainScript.m' and call mainScript() --