Class Constructor Methods

Rules for Constructors

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 always return an initialized
object.

The constructor has the same name as the class.

The only output argument from a constructor is the
object constructed.

The constructor can return only a single argument.

Constructors must always return a valid instance of
the class. Never return an empty object from a class constructor.

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, you must call them from
the subclass constructor explicitly.

If your constructor makes an explicit call to a superclass
constructor, this call must occur before any other reference to the
constructed object.

A class does not need to define a constructor method
unless it is a subclass of a superclass whose constructor requires
arguments. In this case, you must explicitly call the superclass constructor
with the required arguments. See Constructing Subclasses

If a class does not define a constructor, MATLAB supplies
a constructor that takes no arguments and returns a scalar object
whose properties are initialized to empty or the values specified
as defaults in the property definitions. The constructor supplied
by MATLAB also calls all superclass constructors with no arguments.

If you create a class constructor, you should implement
class constructors so that they can be called with no input arguments,
in addition to whatever arguments are normally required See No Input Argument Constructor Requirement.

Constructor functions must return an instance of the
constructor's class. The constructor should avoid assigning
to the constructor output argument because subclasses often call a
superclass constructor in the process of creating an instance of the
subclass.

Calls to superclass constructors cannot be conditional.
This means superclass construction calls cannot be placed in loops,
conditions, switches, try/catch, or nested functions. See No Conditional Calls to Superclass Constructors for more
information.

Restrict access to constructors using method attributes,
as with any method.

Referencing the Object in a Constructor

When initializing the object, for example, by assigning values
to properties, you must 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:

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 to true, the load 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 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
always add a check for zero arguments to the class constructor to
prevent an error if either of the two cases above occur:

Constructing Subclasses

Subclass constructor functions must explicitly call superclass
constructors if the superclass constructors require input arguments.
The subclass constructor must specify these arguments in the call
to the superclass constructor using the constructor output argument.
Here is the syntax:

The class constructor must make all calls to superclass constructors
before any other references to the object. These changes include 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 .

classdef MyClass < SuperClass

MATLAB calls any uncalled constructors in the left-to-right
order in which they are specified in the classdef line. MATLAB passes
no arguments to these functions.

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).

If you must call superclass constructors with different arguments
that depend on some condition, you can 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, upvector and viewangle can
be passed to the superclass constructor:

Zero or More Superclass Arguments

If you must support the 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.

More on Subclasses

Errors During Class Construction

If an error occurs during the construction of a handle class,
the MATLAB class system calls the class destructor on the object
along with the destructors for any objects contained in properties
and any initialized base classes.