matlab.mixin.Heterogeneous Class

Namespace: matlab.mixin

Superclass for heterogeneous array formation

Description

matlab.mixin.Heterogeneous is an abstract class that supports forming 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.

Class Attributes

Abstract	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Methods

Public Methods

cat	Concatenate heterogeneous arrays
horzcat	Horizontal concatenation for heterogeneous arrays
vertcat	Vertically concatenate for heterogeneous arrays

Protected Methods

matlab.mixin.Heterogeneous.getDefaultScalarElement

Return default object for heterogeneous array operations

More About

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

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 containing 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 containing 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 containing an instance of LeafA with another instance of LeafA creates a homogeneous array of class LeafA.

harray = [LeafA LeafA];
class(harray)

ans =
LeafA

Restrictions on Heterogeneous Array Formation

You can form heterogeneous arrays only with objects that are derived from the same hierarchy root (for example, the HierarchyRoot class in the hierarchy shown previously).

You can form heterogeneous arrays with objects that derive from multiple superclasses, but only one branch in the hierarchy can define a heterogeneous root.

Forming a Heterogeneous Array

Heterogeneous arrays are the result of operations that produce arrays containing instances of two or more classes from the heterogeneous hierarchy. Usually, the operation is concatenation or indexed assignment. For example, these statements form a heterogeneous array using indexed assignment.

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

ans = 
Middle

Growing the Array Can Change Its Class

If an array contains objects derived from matlab.mixin.Heterogeneous, assigning new objects into it can change the class of the array. For example, consider a homogeneous array containing objects only of the LeafA class.

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

ans = 
LeafA

Adding an object of a different class derived from the same root to a homogeneous array 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 by inheritance from a superclass.

• The method must be Sealed = true (that is, cannot be overridden by a subclass). If you need to seal an inherited method, see Sealing Inherited Methods.

As with a homogeneous array, the class of the heterogeneous array determines which class method executes for any given method invocation. 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.

classdef HeterogeneousSetGet < matlab.mixin.SetGet & matlab.mixin.Heterogeneous
    properties
        P
    end
    methods(Sealed)
        function varargout = set(obj,varargin)
            [varargout{1:nargout}] = [e-mail](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

Heterogeneous arrays in MATLAB can be created with missing array elements. For example:

• 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, but MATLAB cannot find the class definition of a specific object.

In cases like these, the matlab.mixin.Heterogeneous class calls the method getDefaultScalarElement to create default objects to fill the gaps. This method returns an instance of the root class, which is the direct subclass of matlab.mixin.Heterogeneous in a heterogeneous hierarchy.

When 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 class that is 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.

The getDefaultScalarElement method has the following signature:

methods (Static,Sealed,Access = protected)
   function defaultObject = 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

• Its returned value 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

Heterogeneous arrays require 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

• subsref

• subsasgn

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 preserves the class of the objects and does not form a heterogeneous array.

Concatenating Heterogeneous objects that are 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 do any of these:

• 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:

• Indexed assignment A(k) = B

• Horizontal and vertical concatenations [A B] and [A;B]

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

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

Where for indexed assignment A(k) = B and concatenation [A B]:

• DomClass is the name of the class of the array A.

• objToConvert is the object to be converted, B in this case.

• cobj is a legal member of the heterogeneous hierarchy to which A belongs.

MATLAB issues an error if convertObject returns an object that is not in the hierarchy that class A belongs to.

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 Handle Compatible Classes 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.

Version History

Introduced in R2011a