Folders Containing Class Definitions
Class Definitions on the Path
To call a class method, the class definition must be on the MATLAB® path, as described in the next sections.
Class and Path Folders
There are two types of folders that can contain class definition files.
Path folders — The folder is on the MATLAB path and the folder name does not begin with an
@
character. Use this type of folder when you want multiple classes and functions in one folder. The entire class definition must be contained in one file.Class folders — The folder name begins with an @ character followed by the class name. The folder is not on the MATLAB path, but its parent folder is on the path. Use this type of folder when you want to use multiple files for one class definition.
See the path
function for information about the MATLAB path.
Using Path Folders
The folders that contain class definition files are on the MATLAB path. Therefore, class definitions placed in path folders behave like any ordinary function with respect to precedence—the first occurrence of a name on the MATLAB path takes precedence over all subsequent occurrences of the same name.
The name of each class definition file must match the name of the class that is specified with the classdef
keyword. Using a path folder eliminates the need to create a separate class folder for each class. However, the entire class definition, including all methods, must be contained within a single file.
Suppose that you have three classes defined in a single folder:
.../path_folder/MyClass1.m .../path_folder/MyClass2.m .../path_folder/MyClass3.m
To use these classes, add path_folder
to your MATLAB path:
addpath path_folder
Using Class Folders
The name of a class folder always begins with the @
character
followed by the class name for the folder name. A class folder must be contained in a
path folder, but the class folder is not on the MATLAB path. Place the class definition file inside the class folder, which also
can contain separate method files. The class definition file must have the same name as
the class folder (without the @
character).
.../parent_folder/@MyClass/MyClass.m .../parent_folder/@MyClass/myMethod1.m .../parent_folder/@MyClass/myMethod2.m
Define only one class per folder. All files have a .m
or
.p
extension. For MATLAB versions R2018a and later, standalone methods can be live functions with a
.mlx
extension.
Use a class folder when you want to use more than one file for your class definition. MATLAB treats any function file in the class folder as a method of the class. Function files can be MATLAB code (.m
), Live Code file format (.mlx
), MEX functions (platform dependent extensions), and P-code files (.p
).
MATLAB explicitly identifies any file in a class folder as a method of that class. This enables you to use a more modular approach to authoring methods of your class.
The base name of each file must be a valid MATLAB function name. Valid function names begin with an alphabetic character and can contain letters, numbers, or underscores. For more information, see Methods in Separate Files.
Functions in Private Folders Within Class Folders
Private folders contain functions that are accessible only from functions defined in
folders immediately above the private
folder. Any functions defined
in a private
folder inside a class folder can only be called from the
methods of the class. The functions have access to the private members of the class but
are not themselves methods. They do not require an object to be passed as an input and
can only be called using function notation. Use functions in private
folders when you need helper functions that can be called from multiple methods of your
class.
If a class folder contains a private
folder, only the class defined in that folder can access functions defined in the private
folder. Subclasses do not have access to superclass private functions. For more information on private folders, see Private Functions.
If you want a subclass to have access to the private functions of the superclass, define the functions as protected methods of the superclass. Specify the methods with the Access
attribute set to protected
.
Dispatching to Methods in Private Folders
If a class defines functions in a private
folder that is in a
class folder, then MATLAB follows these precedence rules when dispatching to the private
functions versus the methods of the classdef
file:
Using dot notation (
obj.methodName
), a function in aprivate
folder takes precedence over a method defined in theclassdef
file.Using function notation (
methodName(obj)
), a method defined in theclassdef
file takes precedence over the function in theprivate
folder.
No Class Definitions in Private Folders
You cannot put class definitions (classdef
file) in private folders because doing so would not meet the requirements for class or path folders.
Class Precedence and MATLAB Path
When there are multiple class definitions with the same name, the file location on the MATLAB path determines precedence. The class definition in the folder that comes first on the MATLAB path always takes precedence over any classes that are later on the path, whether or not the definitions are contained in a class folder.
A function with the same name as a class in a path folder takes precedence over the class if the function is in a folder that is earlier on the path. However, a class defined in a class folder (@-folder) takes precedence over a function of the same name, even if the function is defined in a folder that is earlier on the path.
For example, consider a path with the following folders and files.
Order in Path | Folder and File | File Defines |
---|---|---|
1 |
| Class |
2 |
| Function |
3 |
| Class |
4 |
| Method |
5 |
| Class |
MATLAB applies this logic to determine which version of Foo
to
call:
Class fldr1/Foo.m
takes precedence over the class fldr3/@Foo
because:
fldr1
is beforefldr3
on the path, andfldr1/Foo.m
is a class.
Class fldr3/@Foo
takes precedence over function fldr2/Foo.m
because:
fldr3/@Foo
is a class in a class folder.fldr2/Foo.m
is not a class.Classes in class folders take precedence over functions.
Function fldr2/Foo.m
takes precedence over class fldr5/Foo.m
because:
fldr2
comes before classfldr5
on the path.fldr5/Foo.m
is not in a class folder.Classes that are not defined in class folders obey the path order with respect to functions.
Class fldr3/@Foo
takes precedence over
fldr4/@Foo
because:
fldr3
comes beforefldr4
on the path.
If fldr3/@Foo/Foo.m
contains a MATLAB class created before Version 7.6 (that is, the class does not use the
classdef
keyword), then fldr4/@Foo/bar.m
becomes a method of the Foo
class defined in
fldr3/@Foo
.
Previous Behavior of Classes Defined in Class Folders
In MATLAB Versions 5 through 7, class folders do not shadow other class folders having the same name, but residing in later path folders. Instead, the class uses the combination of methods from all class folders having the same name to define the class. This behavior is no longer supported.
For backward compatibility, classes defined in class folders always take precedence over functions and scripts having the same name. This precedence applies to functions and scripts that come before these classes on the path.
Changing Path to Update Class Definition
MATLAB can only recognize one definition of a class as the current definition.
Changing your MATLAB path can change the definition file for a class (see path
). If no instances of the old definition exist (that is, the
definition that is no longer first on the path), MATLAB immediately recognizes the new folder as the current definition. If,
however, you have an existing instance of the class before changing the path, whether
MATLAB uses the definition in the new folder depends on how the new class has
been defined. If the new definition is defined in a class folder, MATLAB immediately recognizes the new folder as the current class definition.
However, for classes that are defined in path folders (that is, not in class
@
folders), you must clear the class before MATLAB recognizes the new folder as the current class definition.
Class Definitions in Class Folders
Suppose that you define two versions of a class named Foo
in two folders, fldA
and fldB
.
fldA/@Foo/Foo.m fldB/@Foo/Foo.m
Add folder fldA
to the top of the path.
addpath fldA
Create an instance of class Foo
. MATLAB uses fldA/@Foo/Foo.m
as the class definition.
a = Foo;
Change the current folder to fldB
.
cd fldB
The current folder is always first on the path. Therefore, MATLAB finds fldB/@Foo/Foo.m
as the definition for class
Foo
.
b = Foo;
MATLAB automatically updates the existing instance, a
, to use the new class definition in fldB
.
Class Definitions in Path Folders
Suppose that you define two versions of a class named Foo
in two folders, fldA
and fldB
, but do not use a class folder.
fldA/Foo.m fldB/Foo.m
Add folder fldA
to the top of the path.
addpath fldA
Create an instance of class Foo
. MATLAB uses fldA/Foo.m
as the class definition.
a = Foo;
Change the current folder to fldB
.
cd fldB
The current folder is effectively the top of the path. However, MATLAB does not identify fldB/Foo.m
as the definition for
class Foo
. MATLAB continues to use the original class definition until you clear the
class.
To use the definition of Foo
in foldB
, clear
Foo
.
clear Foo
MATLAB automatically updates the existing objects to conform to the class definition in fldB
. Usually, clearing instance variables is unnecessary.