Implicit Class Conversion

MATLAB^® can implicitly convert classes in these situations:

Creation or modification of object arrays using concatenation
Creation or modification of object arrays using subscripted assignment
Property validation
Argument validation in function and method calls

To perform the conversion, MATLAB attempts to use a converter method, the constructor of the destination class, or the cast function, depending on the context of the conversion.

Concatenation

In concatenation operations, the dominant object determines the class of the resulting array. MATLAB determines the dominant object according to these rules:

User-defined classes are dominant over built-in classes such as double.
If there is no defined dominance relationship between any two classes, then the leftmost object in the concatenation statement is dominant. For more information on class dominance, see Method Invocation.

For example, A is an instance of ClassA, and B is an instance of ClassB. In the statement C = [A,B], if A is the dominant object, MATLAB attempts to convert B to the class of A.

MATLAB first tries to call a converter method. If no converter method is found, it calls the constructor for ClassA. The concatenation statement is equivalent to:

C = [A,ClassA(B)]

If the call to the ClassA constructor fails to convert B to ClassA, MATLAB issues an error. If the conversion succeeds, MATLAB concatenates A with the converted B.

Subscripted Assignment

In subscripted assignment, the left side of the assignment statement defines the class of the array. If you assign array elements when the right side is a different class than the left side, MATLAB attempts to convert the right side to the class of the left side.

For example, assigning an object of ClassB to an element of array A requires conversion.

A = ClassA;
B = ClassB;
A(2) = B;

MATLAB attempts to perform the conversion by first looking for a converter method. If no converter method is found, it calls the ClassA constructor. The assignment is then equivalent to:

A(2) = ClassA(B)

If calling the constructor fails, MATLAB calls cast:

A(2) = cast(B,"like",A)

If the conversion still fails after these steps, MATLAB issues an error. If the conversion succeeds, MATLAB assigns the converted value to A(2).

Property Validation

When you assign a value to a property that specifies a class restriction as part of its validation, MATLAB uses the built-in function isa to check the relationship between the value and the class. If the value is not the specified class or one of its subclasses, MATLAB attempts to convert the value to the specified class.

To demonstrate the conversion process, refer to these class definitions.

classdef ClassA 
   properties 
     Prop ClassB 
   end
end

classdef ClassB
end

classdef SubClassB < ClassB 
end

classdef ClassC
end

This script shows when MATLAB attempts conversions during property assignments.

A = ClassA; 
B = ClassB; 
SB = SubClassB; 
C = ClassC; 

A.Prop = B; % no conversion 
A.Prop = SB; % no conversion 
A.Prop = C; % conversion required

In this script:

A.Prop = B does not require conversion because B belongs to ClassB, which satisfies the property validation for Prop defined in ClassA.
A.Prop = SB does not require conversion because SB belongs to SubClassB, which is a subclass of ClassB.
A.Prop = C requires conversion because C does not belong to ClassB or its subclass SubClassB.
MATLAB attempts to convert C to ClassB or its subclass SubClassB by first calling ClassB(C). This call can invoke a converter method called ClassB (defined by ClassC) or the ClassB constructor. If calling ClassB(C) does not yield an instance of ClassB or SubClassB, MATLAB attempts to cast the result of ClassB(C) to ClassB as a final step.
If these steps fail to convert C to ClassB or SubClassB, MATLAB issues an error. If the conversion succeeds, MATLAB writes the converted value to A.Prop.

Note

Property class validation does not support implicit conversion of any built-in types to cell arrays, even if you provide your own conversion method.

Function and Method Argument Validation

When you assign a value to a function or method argument that specifies a class restriction as part of its validation, MATLAB uses the built-in function isa to check the relationship between the value and the class. If the value is not the specified class or one of its subclasses, MATLAB attempts to convert the value to the specified class.

To demonstrate the conversion process, refer to these class and function definitions.

classdef ClassA 
end

classdef SubClassA < ClassA
end

classdef ClassB 
end

function test(x)
   arguments
      x ClassA
   end
end

This script shows when MATLAB attempts conversions during argument validation.

A = ClassA; 
SA = SubClassA; 
B = ClassB;  

test(A); % no conversion 
test(SA); % no conversion 
test(B); % conversion required

In this script:

test(A) does not require conversion because A belongs to ClassA, which satisfies the argument validation for x defined in test.
test(SA) does not require conversion because SA belongs to SubClassA, which is a subclass of ClassA.
test(B) requires conversion because B does not belong to ClassA or its subclass SubClassA.
MATLAB attempts to convert B to ClassA or its subclass SubClassA by first calling ClassA(B). This call can invoke a converter method called ClassA (defined by ClassB) or the ClassA constructor. If calling ClassA(B) does not yield an instance of ClassA or SubClassA, MATLAB attempts to cast the result of ClassA(B) to ClassA as a final step.
If these steps fail to convert B to ClassA or SubClassA, MATLAB issues an error. If the conversion succeeds, MATLAB uses the converted value for the function call.

Note

Argument validation does not support implicit conversion of any built-in types to cell arrays, even if you provide your own conversion method.