Main Content

Method Invocation

Determining Which Method Is Invoked

When MATLAB® invokes an ordinary method that has an argument list, it uses the following criteria to determine which method to call

  • The class of the leftmost argument whose class is not specified as inferior to any other argument's class is chosen as the dominant class and its method is invoked.

  • If this class does not define the called method, then a function with that name that is on the MATLAB path is invoked.

  • If no such function exists, MATLAB issues an error indicating that the dominant class does not define the named method.

Dominant Argument

MATLAB uses dominant argument dispatching to determine which version of a method to call. During method dispatching, MATLAB determines the dominant class from among the arguments in the call. In general, all MATLAB classes defined using the classdef syntax have equal precedence for purposes of method dispatching.

Classes defined using the classdef syntax take precedence over these MATLAB classes:

double, single, int64, uint64, int32, uint32, int16, uint16, int8, uint8, char, string, logical, cell, struct, and function_handle.

In general, when two or more objects are part of the argument list, the method defined for the class of the left-most object is invoked. However, user-defined classes can specify the relative dominance of specific classes. For information, see Class Precedence.

For example, suppose classA defines classB as inferior and suppose that both classes define a method called combine.

Calling the method with an object of classB and classA:

combine(B,A)

actually calls the combine method of classA because A is the dominant argument.

Dot Notation vs. Function Notation

MATLAB classes support both function and dot notation syntax for calling methods. For example, if setColor is a method of the class of object X, then calling setColor with function notation would be:

X = setColor(X,'red');

The equivalent method call using dot notation is:

X = X.setColor('red')

However, in certain cases, the results for dot notation can differ with respect to how MATLAB dispatching works:

  • If there is an overloaded subsref, it is invoked whenever using dot notation. That is, the statement is first tested to see if it is subscripted assignment.

  • If there is no overloaded subsref, then setColor must be a method of X. An ordinary function or a class constructor is never called using this notation.

  • Only the argument X (to the left of the dot) is used for dispatching. No other arguments, even if dominant, are considered. Therefore dot notation can call only methods of X; methods of other argument are never called.

Case Where Result Is Different.  Here is an example of a case where dot and function notation can give different results. Suppose that you have the following classes:

  • classA defines a method called methodA that requires an object of classB as one of its arguments

  • classB defines classA as inferior to classB

classdef (InferiorClasses = {?classA}) classB
   ...
end

The methodA method is defined with two input arguments, one of which is an object of classB:

classdef classA
methods
   function methodA(obj,obj_classB)
      ...
   end
end

classB does not define a method with the same name as methodA. Therefore, the following syntax causes MATLAB to search the path for a function with the same name as methodA because the second argument is an object of a dominant class. If a function with that name exists on the path, then MATLAB attempts to call this function instead of the method of classA and most likely returns a syntax error.

obj = classA(...);
methodA(obj,obj_classB)

Dot notation is stricter in its behavior. For example, this call to methodA:

obj = classA(...);
obj.methodA(obj_classB)

can call only methodA of the class of obj.

Referencing Names with Expressions—Dynamic Reference

You can reference an object's properties or methods using an expression in dot-parentheses syntax:

obj.(expression)

The expression must evaluate to a char vector that is the name of a property or a method. For example, the following statements are equivalent:

obj.Property1
obj.('Property1')

In this case, obj is an object of a class that defines a property called Property1. Therefore, you can pass a char variable in the parentheses to reference to property:

propName = 'Property1';
obj.(propName)

You can call a method and pass input arguments to the method using another set of parentheses:

obj.(expression)(arg1,arg2,...)

Using this notation, you can make dynamic references to properties and methods in the same way you can create dynamic references to the fields of structs.

As an example, suppose that an object has methods corresponding to each day of the week. These methods have the same names as the days of the week (Monday, Tuesday, and so on). Also, the methods take as char vector input arguments, the current day of the month (the date). Now suppose that you write a function in which you want to call the correct method for the current day.

Use an expression created with the date and datestr functions:

obj.(datestr(date,'dddd'))(datestr(date,'dd'))

The expression datestr(date,'dddd') returns the current day as a char vector. For example:

datestr(date,'dddd')

ans =

Tuesday

The expression datestr(date,'dd') returns the current date as a char vector. For example:

datestr(date,'dd')

ans =

11

Therefore, the expression using dot-parentheses (called on Tuesday the 11th) is the equivalent of:

obj.Tuesday('11')

Index into Result of Method Call

You can use dot indexing into the result of a method call to obtain a value. For example, this class defines a property and a constructor method. The constructor sets the property value after evaluating an expression using the input argument.

classdef polyEval
    properties
        Result
    end
    methods
        function obj = polyEval(x)
            if nargin
                obj.Result = 2*x.^3 + 7*x.^2 + 2*x + 7;
            end
        end
    end
end

You can index into the result of a call the constructor method to access the value of the property. For example, this call to polyEval() returns the value that is assigned to the property. The instance of the polyEval class is created as a temporary variable and is not saved in the workspace.

 polyEval(-3.5).Result
ans =

     0

In this case, the expression, polyEval(-3.5).Result represents the value 0 (the value -3.5 is a root of the polynomial). You can assign the result of evaluating this expression to a variable or use it in other expressions.

You can dot index into the result of any method that returns a result for which dot indexing is defined, such as an object or structure which can be indexed using a property or field name. You must include the parentheses in all indexing expressions even if there are no arguments. For example, to index into the result of a call to the polyEval() constructor with no inputs, use this expression.

 polyEval().Result

For more information on indexing into the result of function calls, see Indexing into Function Call Results.

Controlling Access to Methods

There can be situations where you want to create methods for internal computation within the class, but do not want to publish these methods as part of the public interface to the class. In these cases, you can use the Access attribute to set the access to one of the following options:

  • public — Any code having access to an object of the class can access this method (the default).

  • private — Restricts method access to the defining class, excluding subclasses. Subclasses do not inherit private methods.

  • protected — Restricts method access to the defining class and subclasses derived from the defining class. Subclasses inherit this method.

  • Access list — Restricts method access to classes in access list. For more information, see Class Members Access

Local and nested functions inside the method files have the same access as the method. Local functions inside a class-definition file have private access to the class defined in the same file.

Invoking Superclass Methods in Subclass Methods

A subclass can override the implementation of a method defined in a superclass. If the subclass method needs to execute additional code instead of completely replacing the superclass method. MATLAB classes can use a special syntax for invocation of superclass methods from a subclass implementation for the same-named method.

The syntax to call a superclass method in a subclass class uses the @ symbol:

MethodName@SuperclassName

For example, the following disp method is defined for a Stock class that is derived from an Asset class. The method first calls the Asset class disp method, passing the Stock object so that the Asset components of the Stock object can be displayed. After the Asset disp method returns, the Stock disp method displays the two Stock properties:

classdef Stock < Asset
   methods   
      function disp(s)
         disp@Asset(s) % Call base class disp method first
         fprintf(1,'Number of shares: %g\nShare price: %3.2f\n',...
         s.NumShares,s.SharePrice);
      end % disp
   end
end

Limitations of Use

The following restrictions apply to calling superclass methods. You can use this notation only within:

  • A method having the same name as the superclass method you are invoking

  • A class that is a subclass of the superclass whose method you are invoking

Invoking Built-In Functions

The MATLAB builtin function enables you to call the built-in version of a function that has been overloaded by a method.

Related Topics