matlab.mixin.Heterogeneous class

Package: matlab.mixin

Superclass for heterogeneous array formation

Description

matlab.mixin.Heterogeneous is an abstract class that provides support for the formation of heterogeneous arrays. A heterogeneous array is an array of objects that differ in their specific class, but are all derived from or are instances of a root class. The root class derives directly from matlab.mixin.Heterogeneous.

Heterogeneous Hierarchy

Use matlab.mixin.Heterogeneous to define hierarchies of classes whose instances you can combine into heterogeneous arrays.

The following class definition enables the formation of heterogeneous arrays that combine instances of any classes derived from HierarchyRoot.

classdef HierarchyRoot < matlab.mixin.Heterogeneous
% HierarchyRoot is a direct subclass of
% matlab.mixin.Heterogeneous
% HierarchyRoot is the root of this heterogeneous hierarchy

Deriving the HierarchyRoot class directly from matlab.mixin.Heterogeneous enables the HierarchyRoot class to become the root of a hierarchy of classes. You can combine instances of the members of this hierarchy into a heterogeneous array. Only instances of classes derived from the same root class can combine to form a valid heterogeneous array.

Class of a Heterogeneous Array

The class of a heterogeneous array is always the class of the most specific superclass common to all objects in the array. For example, suppose you define the following class hierarchy:

Forming an array (harray) of an instance of LeafA with an instance of LeafB creates an array of class Middle:

harray = [LeafA,LeafB];
class(harray)
ans =
Middle

Forming an array (harray) of an instance of LeafC with an instance of LeafD creates an array of class HierarchyRoot:

harray = [LeafC,LeafD];
class(harray)
ans =
HierarchyRoot

Forming an array (harray) of an instance of LeafA with an other instance of LeafA creates a homogeneous array of class LeafA:

harray = [LeafA,LeafA];
class(harray)
ans =
LeafA

    Note:   You cannot form heterogeneous arrays that include instances of classes that are not derived from the same hierarchy root (that is, the HierarchyRoot class in the hierarchy shown previously).

Forming a Heterogeneous Array

Heterogeneous arrays are the result of operations that produces arrays containing instances of two or more classes from the heterogeneous hierarchy. Usually, concatenation or indexed assignment form these arrays. For example, these statements form harray using indexed assignment:

harray(1) = LeafA;
harray(2) = LeafC;
class(harray)
ans = 
Middle

Growing the Array Can Change Its Class

Assigning new objects into an array containing objects derived from matlab.mixin.Heterogeneous can change the class of the array. For example, given a homogeneous array containing objects only of the LeafA class:

harray = [LeafA,LeafA,LeafA];
class(harray)
ans = 
LeafA

Adding an object of another class derived from the same root to harray converts the array's class to the most specific superclass:

harray(4) = LeafB;
class(harray)
ans = 
Middle

Method Dispatching

When MATLAB® invokes a method for which the dominant argument is a heterogeneous array, the method:

  • Must be defined for the class of the heterogeneous array, either directly by the class of the array or inherited from a superclass.

  • Must be Sealed = true (cannot be overridden by a subclass).

The class of the heterogeneous array determines which class method executes for any given method invocation, as is the case with a homogeneous array. MATLAB does not consider the class of individual elements in the array when dispatching to methods.

Sealing Inherited Methods

The requirement that methods called on a heterogeneous array be Sealed = true ensures correct and predictable behavior with all array elements.

You must override methods that are inherited from outside the heterogeneous hierarchy if these methods are not Sealed = true and you want to call these methods on heterogeneous arrays.

For example, suppose you define a heterogeneous array by subclassing matlab.mixin.SetGet, in addition to matlab.mixin.Heterogeneous. Override the set method to call the matlab.mixin.SetGet superclass method as required by your class design:

methods(Sealed)
   function varargout = set(obj,varargin)
      if nargout == 0
         set@matlab.mixin.SetGet(obj, varargin{:}); 
      else
         varargout{:} = set@matlab.mixin.SetGet(obj,varargin{:});
      end
   end
end

Method implementations can take advantage of the fact that, given a heterogeneous array harray, and a scalar index n, the expression

harray(n)

is not a heterogeneous array. Therefore, when invoking a method on a single element of a heterogeneous array, special requirements for heterogeneous arrays do not apply.

Defining the Default Object

When working with object arrays (both heterogeneous and homogeneous), MATLAB creates default objects to fill in missing array elements by calling the class constructor with no arguments. Filling in missing array elements becomes necessary in cases such as:

  • Indexed assignment creates an array with gaps. For example, if harray is not previously defined:

    harray(5) = LeafA;
  • Loading a heterogeneous array from a MAT-file when MATLAB cannot find the class definition of a specific object.

The matlab.mixin.Heterogeneous class provides a default implementation of a method called getDefaultScalarElement. This method returns an instance of the root class of the heterogeneous hierarchy, unless the root class is abstract.

If the root class is abstract or is not an appropriate default object for the classes in the heterogeneous hierarchy, you can override the getDefaultScalarElement method to return an instance of a class derived from the root class.

Defining the getDefaultScalarElement Method

Specify the class of the default object by overriding the matlab.mixin.Heterogeneous method called getDefaultScalarElement in the root class of the heterogeneous hierarchy. You can override getDefaultScalarElement only in the root class (direct subclasses of matlab.mixin.Heterogeneous).

getDefaultScalarElement has the following signature:

methods (Static, Sealed, Access = protected)
   function default_object = getDefaultScalarElement
   ...
   end
end

The getDefaultScalarElement method must satisfy these criteria:

  • Static — MATLAB calls this method without an object.

  • Protected — MATLAB calls this method, object users do not.

  • Sealed (not required) — Seal this method to ensure users of the heterogeneous hierarchy do not change the intended behavior of the class.

  • It must return a scalar object

  • It must pass the isa test for the root class, that is:

    (isa(getDefaultScalarElement,'HierarchyRoot')

    where HierarchyRoot is the name of the heterogeneous hierarchy root class. This means the default object can be an instance of any class derived from the root class.

Cannot Redefine Indexing or Concatenation

The use of heterogeneous arrays requires consistent indexing and concatenation behaviors. Therefore, subclasses of matlab.mixin.Heterogeneous cannot change their default indexed reference, indexed assignment, or concatenation behavior.

You cannot override the following methods in your subclasses:

  • cat

  • horzcat

  • vertcat

  • subref

  • subsasign

In cases involving multiple inheritance in which your subclass inherits from superclasses in addition to matlab.mixin.Heterogeneous, the superclasses cannot define any of these methods.

Default Concatenation Behavior

Statements of the form:

a = [obj1,obj2,...];

create an array, a, containing the objects listed in brackets.

Concatenating Heterogeneous objects of the same specific class retains the class of the objects and does not form a heterogeneous array.

Concatenating Heterogeneous objects derived from the same root superclass, but that are of different specific classes, yields a heterogeneous array. MATLAB does not attempt to convert the class of any array members if all are part of the same root hierarchy.

Indexed Assignment Behavior

Statements of the form:

a(m:n) = [objm,...objn];

assign the right-hand side objects to the array elements (m:n), specified on the left side of the assignment.

Indexed assignment to a heterogeneous array can:

  • Increase or decrease the size of the array

  • Overwrite existing array elements

  • Change property values of objects within the array

  • Change the class of the array

  • Change whether the array is heterogeneous

Indexed Reference Behavior

Statements of the form:

a = harray(m:n);

assign the elements of harray referenced by indices m:n, to array a.

Indexed reference on a heterogeneous array returns a sub-range of the original array. Depending on the specific elements within that sub-range (m:n), the result might have a different class than the original array, and might not be heterogeneous.

Converting Nonmember Objects

If you attempt to form a heterogeneous array with objects that are not derived from the same root class, MATLAB calls the convertObject method, if it exists, to convert objects to the dominant class. Implementing a convertObject method enables the formation of heterogeneous arrays containing objects that are not part of the heterogeneous hierarchy.

When Is Conversion Necessary

Suppose there are two classes A and B, where B is not derived from matlab.mixin.Heterogeneous, or where A and B are derived from different root classes that are derived from matlab.mixin.Heterogeneous.

MATLAB attempts to call the convertObject method implemented by the root class of A in the following cases:

  • The indexed assignment:

    A(k) = B
  • Horizontal and vertical concatenations:

    [A,B] and [A;B]

Implement a convertObject method if you want to support conversion of objects whose class is not defined in your heterogeneous hierarchy. You do not need to implement this method if your class design does not require this conversion.

Implementing convertObject

Only the root class of the heterogeneous hierarchy can implement a convertObject method.

The convertObject method must have the following signature:

Method (Static, Sealed, Access = protected)
   function cobj = convertObject('DomClass',objToConvert)
   ...
   end
end

For indexed assignment A(k) = B and concatenation [A,B]:

  • DomClass — Name of the class of the array A

  • objToConvert — Object to be converted, B in this case

  • cobj — Legal member of the heterogeneous hierarchy to which A belongs

You must implement convertObject to return a valid object of class A or MATLAB issues an error.

Handle Compatibility

The matlab.mixin.Heterogeneous class is handle compatible. It can be combined with either handle or value classes when defining a subclass using multiple superclasses. See Supporting Both Handle and Value Subclasses for information on handle compatibility.

The matlab.mixin.Heterogeneous class is a value class. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation

Methods

catConcatenation for heterogeneous arrays
getDefaultScalarElementReturn default object for heterogeneous array operations
horzcatHorizontal concatenation for heterogeneous arrays
vertcatVertical concatenation for heterogeneous arrays
Was this topic helpful?