Class Constructor Methods
Purpose of Class Constructor Methods
A constructor method is a special function that creates an instance of the class. Typically, constructor methods accept input arguments to assign the data stored in properties and return an initialized object.
For a basic example, see Creating a Simple Class.
MATLAB® classes that do not explicitly define any class constructors have a default constructor method. This method returns an object of the class that is created with no input arguments. A class can define a constructor method that overrides the default constructor. An explicitly defined constructor can accept input arguments, initialize property values, call other methods, and perform other operations necessary to create objects of the class.
Basic Structure of Constructor Methods
Constructor methods can be structured into three basic sections:
Pre-initialization — Compute arguments for superclass constructors.
Object initialization — Call superclass constructors.
Post initialization — Perform any operations related to the subclass, including referencing and assigning to the object, call class methods, passing the object to functions, and so on.
This code illustrates the basic operations performed in each section:
classdef ConstructorDesign < BaseClass1 properties ComputedValue end methods function obj = ConstructorDesign(a,b,c) %% Pre Initialization %% % Any code not using output argument (obj) if nargin == 0 % Provide values for superclass constructor % and initialize other inputs a = someDefaultValue; args{1} = someDefaultValue; args{2} = someDefaultValue; else % When nargin ~= 0, assign to cell array, % which is passed to supclass constructor args{1} = b; args{2} = c; end compvalue = myClass.staticMethod(a); %% Object Initialization %% % Call superclass constructor before accessing object % You cannot conditionalize this statement obj = obj@BaseClass1(args{:}); %% Post Initialization %% % Any code, including access to object obj.classMethod(arg); obj.ComputedValue = compvalue; ... end ... end ... end
Call the constructor like any function, passing arguments and returning an object of the class.
obj = ConstructorDesign(a,b,c);
Guidelines for Constructors
The constructor has the same name as the class.
The constructor can return multiple arguments, but the first output must be the object created.
If you do not want to assign the output argument, you can clear the object variable in the constructor (see Output Object Suppressed).
If you create a class constructor, ensure it can be called with no input arguments. See No Input Argument Constructor Requirement.
If your constructor makes an explicit call to a superclass constructor, this call must occur before any other reference to the constructed object and cannot occur after a
return
statement.Calls to superclass constructors cannot be conditional. You cannot place superclass construction calls in loops, conditions, switches, try/catch, or nested functions. See No Conditional Calls to Superclass Constructors for more information.
Default Constructor
If a class does not define a constructor, MATLAB supplies a default constructor that takes no arguments and returns a scalar object whose properties are initialized to property default values. The default constructor supplied by MATLAB also calls all superclass constructors with no arguments or with any argument passed to the default subclass constructor.
When a subclass does not define a constructor, the default constructor passes its inputs to the direct superclass constructor. This behavior is useful when there is no need for a subclass to define a constructor, but the superclass constructor does require input arguments.
When to Define Constructors
Define a constructor method to perform object initialization that a default constructor cannot perform. For example, when creating an object of the class requires:
Input arguments
Initializing object state, such as property values, for each instance of the class
Calling the superclass constructor with values that are determined by the subclass constructor
Related Information
For information specific to constructing enumerations, see Enumeration Class Constructor Calling Sequence.
For information on creating object arrays in the constructor, see Create and Initialize Object Arrays.
If the class being created is a subclass, MATLAB calls the constructor of each superclass class to initialize the object. Implicit calls to the superclass constructor are made with no arguments. If superclass constructors require arguments, call them from the subclass constructor explicitly. See Control Sequence of Constructor Calls
Initializing Objects in Constructor
Constructor methods return an initialized object as an output argument. The output argument is created when the constructor executes, before executing the first line of code.
For example, the following constructor can assign the value of the object's property A
as the first statement because the object obj
has already been assigned to an instance of MyClass
.
function obj = MyClass(a,b,c) obj.A = a; ... end
You can call other class methods from the constructor because the object is already initialized.
The constructor also creates an object whose properties have their default values — either empty ([]
) or the default value specified in the property definition block.
For example, this constructor operates on the input arguments to assign the value of the Value
property.
function obj = MyClass(a,b,c) obj.Value = (a + b) / c; ... end
Referencing the Object in a Constructor
When initializing the object, for example, by assigning values to properties, use the name of the output argument to refer to the object within the constructor. For example, in the following code the output argument is obj
and the object is reference as obj
:
% obj is the object being constructed function obj = MyClass(arg) obj.property1 = arg*10; obj.method1; ... end
For more information on defining default property values, see Define Properties with Default Values.
Setting Properties Using Name-Value Arguments
When initializing an object, you can use the
structName
.?ClassName
syntax to enable passing in property values as name-value arguments. For
example, NameValueClass
, the constructor collects any passed
arguments into the struct opts
, then uses a
for
-loop to set the property values.
classdef NameValueClass properties Property1 Property2 end properties (SetAccess=immutable) ImmProperty end methods function obj = NameValueClass(opts) arguments opts.?NameValueClass end for prop = string(fieldnames(opts))' obj.(prop) = opts.(prop); end end end end
Call the class constructor and set ImmProperty
using the
name-value syntax.
x = NameValueClass(ImmProperty=1)
x = NameValueClass with properties: Property1: [] Property2: [] ImmProperty: 1
For more information on using class properties as name-value arguments in a function, see Name-Value Arguments from Class Properties.
Before R2024a: The
structName
.?ClassName
syntax did not work with immutable properties. To use this technique in earlier
releases, use a separate line to define a name-value argument that matches the
immutable property. For example, in
NameValueClass
:arguments
opts.ImmProperty
opts.?NameValueClass
end
No Input Argument Constructor Requirement
There are cases where the constructor must be able to be called with no input argument:
When loading objects into the workspace, if the class
ConstructOnLoad
attribute is set totrue
, theload
function calls the class constructor with no arguments.When creating or expanding an object array such that not all elements are given specific values, the class constructor is called with no arguments to fill in unspecified elements (for example,
x(10,1) = MyClass(a,b,c);
). In this case, the constructor is called once with no arguments to populate the empty array elements (x(1:9,1)
) with copies of this one object.
If there are no input arguments, the constructor creates an object using only default properties values. A good practice is to add a check for zero arguments to the class constructor to prevent an error if either of these two cases occur:
function obj = MyClass(a,b,c) if nargin > 0 obj.A = a; obj.B = b; obj.C = c; ... end end
For ways to handle superclass constructors, see Basic Structure of Constructor Methods.
Subclass Constructors
Subclass constructors can call superclass constructors explicitly to pass arguments to the superclass constructor. The subclass constructor must specify these arguments in the call to the superclass constructor and must use the constructor output argument to form the call. Here is the syntax:
classdef MyClass < SuperClass methods function obj = MyClass(a,b,c,d) obj@SuperClass(a,b); ... end end end
The subclass constructor must make all calls to superclass constructors before any other references to the object (obj
). This restriction includes assigning property values or calling ordinary class methods. Also, a subclass constructor can call a superclass constructor only once.
Reference Only Specified Superclasses
If the classdef
does not specify the class as a superclass, the constructor cannot call a superclass constructor with this syntax. That is, subclass constructor can call only direct superclass constructors listed in the classdef
line.
classdef MyClass < SuperClass1 & SuperClass2
MATLAB calls any uncalled constructors in the left-to-right order in which they are specified in the classdef
line. MATLAB passes no arguments with these calls.
No Conditional Calls to Superclass Constructors
Calls to superclass constructors must be unconditional. There can be only one call for a given superclass. Initialize the superclass portion of the object by calling the superclass constructors before using the object (for example, to assign property values or call class methods).
To call a superclass constructor with different arguments that depend on some condition, build a cell array of arguments and provide one call to the constructor.
For example, the Cube
class constructor calls the superclass Shape
constructor using default values when the Cube
constructor is called with no arguments. If the Cube
constructor is called with four input arguments, then pass upvector
and viewangle
to the superclass constructor:
classdef Cube < Shape properties SideLength = 0 Color = [0 0 0] end methods function cubeObj = Cube(length,color,upvector,viewangle) % Assemble superclass constructor arguments if nargin == 0 super_args{1} = [0 0 1]; super_args{2} = 10; elseif nargin == 4 super_args{1} = upvector; super_args{2} = viewangle; else error('Wrong number of input arguments') end % Call superclass constructor cubeObj@Shape(super_args{:}); % Assign property values if provided if nargin > 0 cubeObj.SideLength = length; cubeObj.Color = color; end ... end ... end end
Zero or More Superclass Arguments
To support a syntax that calls the superclass constructor with no arguments, provide this syntax explicitly.
Suppose in the case of the Cube
class example, all property values in the Shape
superclass and the Cube
subclass have default values specified in the class definitions. Then you can create an instance of Cube
without specifying any arguments for the superclass or subclass constructors.
Here is how you can implement this behavior in the Cube
constructor:
methods function cubeObj = Cube(length,color,upvector,viewangle) % Assemble superclass constructor arguments if nargin == 0 super_args = {}; elseif nargin == 4 super_args{1} = upvector; super_args{2} = viewangle; else error('Wrong number of input arguments') end % Call superclass constructor cubeObj@Shape(super_args{:}); % Assign property values if provided if nargin > 0 cubeObj.SideLength = length; cubeObj.Color = color; end ... end end
More on Subclasses
See Design Subclass Constructors for information on creating subclasses.
Implicit Call to Inherited Constructor
MATLAB passes arguments implicitly from a default subclass constructor to the superclass constructor. This behavior eliminates the need to implement a constructor method for a subclass only to pass arguments to the superclass constructor.
For example, the following class constructor requires one input argument (a datetime
object), which the constructor assigns to the CurrentDate
property.
classdef BaseClassWithConstr properties CurrentDate datetime end methods function obj = BaseClassWithConstr(dt) obj.CurrentDate = dt; end end end
Suppose that you create a subclass of BaseClassWithConstr
, but your subclass does not require an explicit constructor method.
classdef SubclassDefaultConstr < BaseClassWithConstr ... end
You can construct an object of the SubclassDefaultConstr
by calling its default constructor with the superclass argument:
obj = SubclassDefaultConstr(datetime);
For information on subclass constructors, see Subclass Constructors and Default Constructor.
Errors During Class Construction
For handle classes, MATLAB calls the delete
method when an error occurs under the following conditions:
A reference to the object is present in the code prior to the error.
An early
return
statement is present in the code before the error.
MATLAB calls the delete
method on the object, the delete
methods for any objects contained in properties, and the delete
methods for any initialized base classes.
Depending on when the error occurs, MATLAB can call the class destructor before the object is fully constructed. Therefore class delete
methods must be able to operate on partially constructed objects that might not have values for all properties. For more information, see Support Destruction of Partially Constructed Objects.
For information on how objects are destroyed, see Handle Class Destructor.
Output Object Suppressed
You can suppress the assignment of the class instance to the ans
variable when no output variable is assigned in a call to the constructor. This technique is useful for apps that creates graphical interface windows that hold onto the constructed objects. These apps do not need to return the object.
Use nargout
to determine if the constructor has been called with an output argument. For example, the class constructor for the MyApp
class clears the object variable, obj
, if called with no output assigned:
classdef MyApp methods function obj = MyApp ... if nargout == 0 clear obj end end ... end end
When a class constructor does not return an object, MATLAB does not trigger the matlab.metadata.Class
InstanceCreated
event.