Folders Containing Class Definitions - MATLAB & Simulink (original) (raw)
You can use different types of folders to define and organize classes in MATLAB®.
- Path folders — This type of folder is on the MATLAB path, and the folder name does not begin with a
+or@character. Use this type of folder when you want to include multiple classes and functions in one folder. In a path folder, each class definition must be contained in one file. - Class folders — The folder name begins with an
@character followed by the class name. This type of 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. - Namespace folders — The folder name begins with a
+character followed by the class name. Namespaces are special folders that can contain class folders, class definition files, function files, and other namespaces (referred to as inner namespaces). Because the folder names become part of the class name, a namespace creates more robust names for the items contained inside it.
This topic covers the use of path and class folders. For more information on namespaces, see Create Namespaces.
Using Path Folders
Because path folders are on the MATLAB path, 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. You can define multiple classes in the same path folder, but each class definition, including all methods, must be contained within one 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.
Using Class Folders
The name of a class folder always begins with the @ character followed by the class name that the folder contains. A class folder must be contained in a path folder. Place the class definition file inside the class folder, which also can contain separate method files. For example, MyClass and two of its methods are defined inside the @MyClass folder.
.../parent_folder/@MyClass/MyClass.m .../parent_folder/@MyClass/myMethod1.m .../parent_folder/@MyClass/myMethod2.m
To use these classes, add path_folder to your MATLAB path.
Use a class folder when you want to use more than one file for your class definition. Define only one class per class folder. MATLAB treats any function file in the class folder as a method of the class. Class definition files can have a .m or .p extension. Function files can be MATLAB code (.m), live code (.mlx), MEX functions (platform-dependent extensions), and P-code (.p).
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 method defined in theclassdeffile takes precedence over a function of the same name in theprivatefolder. - Using function notation (
methodName(obj)), a function in aprivatefolder takes precedence over a method of the same name defined in theclassdeffile.
Note
You cannot put class definitions inside private 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 takes precedence over any classes that are later on the path.
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, this path has a function and a class with the same name. Even though the function Foo in fldr1 is earlier in the path, the class Foo in fldr2 takes precedence because it is defined in a class folder.
| Order in Path | Folder and File | File Defines |
|---|---|---|
| 1 | fldr1/Foo.m | Function Foo |
| 2 | fldr2/@Foo/Foo.m | Class Foo |
Precedence of Classes in @-folders over Functions of the Same Name Will Be Removed in a Future Release
In a future release, the rule giving precedence to a class defined in a class folder (@-folder) over a function of the same name, regardless of position on the path, will be removed. Starting in R2024a, MATLAB issues a warning when these three conditions are met:
- You have a class defined in a class folder and a function with the same name on your path.
- The function appears earlier in the path order than the class.
- You use the name of the function and class.
To ensure the class still has precedence after the rule change and avoid the warning, use one of these options:
- Update your path configuration to place the class earlier than the function on the path. For more information on working with the path, seeWhat Is the MATLAB Search Path?
- Remove the function from the path.
- Rename the function.
To permanently give the function precedence and avoid the warning, use one of these options:
- Remove the class from the path.
- Rename the class.
Changing the Path to Update Class Definitions
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). MATLAB follows these rules for updating class definitions after a change to the path:
- When a class definition is removed from the path, MATLAB clears the class definition unless there are existing instances of that class in the workspace.
- When a new class definition is added to the path and it takes precedence over an old definition of the same name, MATLAB uses the new definition. MATLAB updates existing instances of the class the next time those instances are accessed.
- If you change the path in the middle of a script or function and a class is updated during that change, MATLAB does not update or clear any class definitions until the script or function finishes executing.
Note
Changing the current folder is also a path change, and class definitions in the current folder always take precedence over definitions in the path.
Before R2024b: The type of folder a class definition is contained in affects how MATLAB updates class definitions after path changes. MATLAB immediately updates class definitions when the new definition is in a class folder (@-folder), but for classes defined in path folders, you must clear the old definition before MATLAB recognizes the new definition.