Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Folders Containing Class Definitions

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 in one folder. However, the entire class definition must be contained in one .m 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 class definition files in the folders 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/MyClass2.m

To use these classes, add path_folder to your MATLAB path:

addpath path_folder

Using Class Folders

A class folder name 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). The class definition (beginning with the classdef keyword) must appear in the file before any other code (white space and comments do not constitute code).

.../parent_folder/@MyClass/MyClass.m
.../parent_folder/@MyClass/myMethod1.m
.../parent_folder/@MyClass/myMethod2.m

Define only one class per folder. All files must have a .m extension.

Use a class folder when you want to use more than one file for your class definition. MATLAB treats any .m file in the class folder as a method of the class. Class files provide the advantage that MATLAB can explicitly identify any file in the folder as a method of that class. For more information, see Changing Path to Update Class Definition.

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.

Access to Functions Defined in Private Folders

Private folders contain functions that are accessible only from functions defined in folders immediately above the private folder. If a class folder contains a private folder, only the class (or classes) 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, a better approach is to define the functions as protected methods of the superclass. Define the methods with the Access attribute set to protected.

No Class Definitions in Private Folders

You cannot put class definitions 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 definition files with the same name, the file location on the MATLAB path determines the file precedence. All class definition files before a class on the path take precedence, whether or not the definitions are contained in a class folder. The class takes precedence over all class definition files occurring later on the path.

For example, consider a path with the following folders, containing the files indicated.

Order in PathFolder and FileFile Defines

1

fldr1/Foo.m

Class Foo

2

fldr2/Foo.m

Function Foo

3

fldr3/@Foo/Foo.m

Class Foo

4

fldr4/@Foo/bar.m

Method bar

5

fldr5/Foo.m

Class Foo

Here is the logic that MATLAB applies to determine which version of Foo to call:

Class fldr1/Foo.m takes precedence over the class fldr3/@Foo because:

  • fldr1/Foo.m is before fldr3/@Foo on the path

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/Foo.m comes before class fldr5/Foo.m 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 class fldr4/@Foo because:

  • The method bar is not recognized as part of the Foo class defined in fldr3/@Foo.

If fldr3/@Foo/Foo.m does not contain a classdef keyword (that is, it is a MATLAB class prior to Version 7.6), 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

Changing your MATLAB path can change the class definition file for a class (see path). 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/+FooPkg/@Foo/Foo.m
fldB/+FooPkg/@Foo/Foo.m

Add folder fldA to the top of the path.

addpath fldA

Create an instance of class FooPkg.Foo. MATLAB uses fldA/+FooPkg/@Foo/Foo.m as the class definition.

a = FooPkg.Foo;

Change the current folder to fldB.

cd fldB

The current folder is always first on the path. Therefore, MATLAB finds fldB/+FooPkg/@Foo/Foo.m as the definition for class FooPkg.Foo.

b = FooPkg.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/+FooPkg/Foo.m
fldB/+FooPkg/Foo.m

Add folder fldA to the top of the path.

addpath fldA

Create an instance of class FooPkg.Foo. MATLAB uses fldA/+FooPkg/@Foo/Foo.m as the class definition.

a = FooPkg.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/+FooPkg/Foo.m as the definition for class FooPkg.Foo. MATLAB continues to use the original class definition until you clear the class.

To use the definition of FooPkg.Foo in foldB, clear FooPkg.Foo.

clear FooPkg.Foo

MATLAB automatically updates the existing objects to conform to the class definition in fldB. In most cases, clearing instance variables is unnecessary.

More About

Was this topic helpful?